diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst index d1620d34b..0659bab6e 100644 --- a/classes/class_@gdscript.rst +++ b/classes/class_@gdscript.rst @@ -170,7 +170,7 @@ Methods +-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`sinh` **(** :ref:`float` s **)** | +-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`smoothstep` **(** :ref:`float` from, :ref:`float` to, :ref:`float` weight **)** | +| :ref:`float` | :ref:`smoothstep` **(** :ref:`float` from, :ref:`float` to, :ref:`float` s **)** | +-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`sqrt` **(** :ref:`float` s **)** | +-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -271,8 +271,7 @@ Returns the absolute value of parameter ``s`` (i.e. positive value). :: - # a is 1 - a = abs(-1) + a = abs(-1) # a is 1 ---- @@ -280,7 +279,7 @@ Returns the absolute value of parameter ``s`` (i.e. positive value). - :ref:`float` **acos** **(** :ref:`float` s **)** -Returns the arc cosine of ``s`` in radians. Use to get the angle of cosine ``s``. +Returns the arc cosine of ``s`` in radians. Use to get the angle of cosine ``s``. ``s`` must be between ``-1.0`` and ``1.0`` (inclusive), otherwise, :ref:`acos` will return :ref:`NAN`. :: @@ -293,7 +292,7 @@ Returns the arc cosine of ``s`` in radians. Use to get the angle of cosine ``s`` - :ref:`float` **asin** **(** :ref:`float` s **)** -Returns the arc sine of ``s`` in radians. Use to get the angle of sine ``s``. +Returns the arc sine of ``s`` in radians. Use to get the angle of sine ``s``. ``s`` must be between ``-1.0`` and ``1.0`` (inclusive), otherwise, :ref:`asin` will return :ref:`NAN`. :: @@ -306,17 +305,19 @@ Returns the arc sine of ``s`` in radians. Use to get the angle of sine ``s``. - void **assert** **(** :ref:`bool` condition, :ref:`String` message="" **)** -Asserts that the ``condition`` is ``true``. If the ``condition`` is ``false``, an error is generated and the program is halted until you resume it. Only executes in debug builds, or when running the game from the editor. Use it for debugging purposes, to make sure a statement is ``true`` during development. +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:`push_error` for reporting errors to project developers or add-on users. + +**Note:** 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. The optional ``message`` argument, if given, is shown in addition to the generic "Assertion failed" message. You can use this to provide additional details about why the assertion failed. :: - # Imagine we always want speed to be between 0 and 20 - speed = -10 + # Imagine we always want speed to be between 0 and 20. + var speed = -10 assert(speed < 20) # True, the program will continue assert(speed >= 0) # False, the program will stop - assert(speed >= 0 && speed < 20) # You can also combine the two conditional statements in one check + assert(speed >= 0 and speed < 20) # You can also combine the two conditional statements in one check assert(speed < 20, "speed = %f, but the speed limit is 20" % speed) # Show a message with clarifying details ---- @@ -375,10 +376,10 @@ Rounds ``s`` upward (towards positive infinity), returning the smallest whole nu :: - i = ceil(1.45) # i is 2 - i = ceil(1.001) # i is 2 + a = ceil(1.45) # a is 2.0 + a = ceil(1.001) # a is 2.0 -See also :ref:`floor`, :ref:`round`, and :ref:`stepify`. +See also :ref:`floor`, :ref:`round`, :ref:`stepify`, and :ref:`int`. ---- @@ -406,13 +407,9 @@ Clamps ``value`` and returns a value not less than ``min`` and not more than ``m :: - speed = 1000 - # a is 20 - a = clamp(speed, 1, 20) - - speed = -10 - # a is 1 - a = clamp(speed, 1, 20) + a = clamp(1000, 1, 20) # a is 20 + a = clamp(-10, 1, 20) # a is 1 + a = clamp(15, 1, 20) # a is 15 ---- @@ -441,9 +438,8 @@ Returns the cosine of angle ``s`` in radians. :: - # Prints 1 then -1 - print(cos(PI * 2)) - print(cos(PI)) + a = cos(TAU) # a is 1.0 + a = cos(PI) # a is -1.0 ---- @@ -455,8 +451,7 @@ Returns the hyperbolic cosine of ``s`` in radians. :: - # Prints 1.543081 - print(cosh(1)) + print(cosh(1)) # Prints 1.543081 ---- @@ -484,8 +479,7 @@ Returns the result of ``value`` decreased by ``step`` \* ``amount``. :: - # a = 59 - a = dectime(60, 10, 0.1)) + a = dectime(60, 10, 0.1)) # a is 59.0 ---- @@ -497,8 +491,7 @@ Converts an angle expressed in degrees to radians. :: - # r is 3.141593 - r = deg2rad(180) + r = deg2rad(180) # r is 3.141593 ---- @@ -506,7 +499,7 @@ Converts an angle expressed in degrees to radians. - :ref:`Object` **dict2inst** **(** :ref:`Dictionary` dict **)** -Converts a previously converted instance to a dictionary, back into an instance. Useful for deserializing. +Converts a dictionary (previously created with :ref:`inst2dict`) back to an instance. Useful for deserializing. ---- @@ -524,7 +517,7 @@ Easing function, based on exponent. The curve values are: 0 is constant, 1 is li The natural exponential function. It raises the mathematical constant **e** to the power of ``s`` and returns it. -**e** has an approximate value of 2.71828. +**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`. @@ -542,14 +535,13 @@ Rounds ``s`` downward (towards negative infinity), returning the largest whole n :: - # a is 2.0 - a = floor(2.99) - # a is -3.0 - a = floor(-2.99) + a = floor(2.45) # a is 2.0 + a = floor(2.99) # a is 2.0 + a = floor(-2.99) # a is -3.0 -See also :ref:`ceil`, :ref:`round`, and :ref:`stepify`. +See also :ref:`ceil`, :ref:`round`, :ref:`stepify`, and :ref:`int`. -**Note:** This method returns a float. If you need an integer, you can use ``int(s)`` directly. +**Note:** This method returns a float. If you need an integer and ``s`` is a non-negative number, you can use ``int(s)`` directly. ---- @@ -561,8 +553,7 @@ Returns the floating-point remainder of ``a/b``, keeping the sign of ``a``. :: - # Remainder is 1.5 - var remainder = fmod(7, 5.5) + r = fmod(7, 5.5) # r is 1.5 For the integer remainder operation, use the % operator. @@ -708,6 +699,10 @@ Returns a normalized value considering the given range. This is the opposite of Returns ``true`` if ``a`` and ``b`` are approximately equal to each other. +Here, approximately equal means that ``a`` and ``b`` are within a small internal epsilon of each other, which scales with the magnitude of the numbers. + +Infinity values of the same sign are considered equal. + ---- .. _class_@GDScript_method_is_inf: @@ -826,6 +821,8 @@ Loads a resource from the filesystem located at ``path``. The resource is loaded **Important:** The path must be absolute, a local path will just return ``null``. +This method is a simplified version of :ref:`ResourceLoader.load`, which can be used for more advanced scenarios. + ---- .. _class_@GDScript_method_log: @@ -840,6 +837,8 @@ Natural logarithm. The amount of time needed to reach a certain level of continu log(10) # Returns 2.302585 +**Note:** The logarithm of ``0`` returns ``-inf``, while negative values return ``-nan``. + ---- .. _class_@GDScript_method_max: @@ -878,7 +877,9 @@ Use a negative ``delta`` value to move away. :: + move_toward(5, 10, 4) # Returns 9 move_toward(10, 5, 4) # Returns 6 + move_toward(10, 5, -1.5) # Returns 11.5 ---- @@ -886,13 +887,20 @@ Use a negative ``delta`` value to move away. - :ref:`int` **nearest_po2** **(** :ref:`int` value **)** -Returns the nearest larger power of 2 for integer ``value``. +Returns the nearest equal or larger power of 2 for integer ``value``. + +In other words, returns the smallest value ``a`` where ``a = pow(2, n)`` such that ``value <= a`` for some non-negative integer ``n``. :: nearest_po2(3) # Returns 4 nearest_po2(4) # Returns 4 nearest_po2(5) # Returns 8 + + nearest_po2(0) # Returns 0 (this may not be what you expect) + nearest_po2(-1) # Returns 0 (this may not be what you expect) + +**WARNING:** Due to the way it is implemented, this function returns ``0`` rather than ``1`` for non-positive values of ``value`` (in reality, 1 is the smallest integer power of 2). ---- @@ -951,7 +959,7 @@ Returns the integer modulus of ``a/b`` that wraps equally in positive and negati :: for i in range(-3, 4): - print("%2.0f %2.0f %2.0f" % [i, i % 3, posmod(i, 3)]) + print("%2d %2d %2d" % [i, i % 3, posmod(i, 3)]) Produces: @@ -971,11 +979,11 @@ Produces: - :ref:`float` **pow** **(** :ref:`float` base, :ref:`float` exp **)** -Returns the result of ``x`` raised to the power of ``y``. +Returns the result of ``base`` raised to the power of ``exp``. :: - pow(2, 5) # Returns 32 + pow(2, 5) # Returns 32.0 ---- @@ -998,12 +1006,14 @@ Returns a :ref:`Resource` from the filesystem located at ``path` - void **print** **(** ... **)** |vararg| -Converts one or more arguments to strings in the best way possible and prints them to the console. +Converts one or more arguments of any type to string in the best way possible and prints them to the console. :: a = [1, 2, 3] - print("a", "b", a) # Prints ab[1, 2, 3] + print("a", "=", a) # Prints a=[1, 2, 3] + +**Note:** Consider using :ref:`push_error` and :ref:`push_warning` to print error and warning messages instead of :ref:`print`. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. ---- @@ -1091,6 +1101,8 @@ Pushes an error message to Godot's built-in debugger and to the OS terminal. push_error("test error") # Prints "test error" to debugger and terminal as error call +**Note:** Errors printed this way will not pause project execution. To print an error message and pause project execution in debug builds, use ``assert(false, "test error")`` instead. + ---- .. _class_@GDScript_method_push_warning: @@ -1113,7 +1125,7 @@ Converts an angle expressed in radians to degrees. :: - rad2deg(0.523599) # Returns 30 + rad2deg(0.523599) # Returns 30.0 ---- @@ -1153,7 +1165,7 @@ Returns a random floating point value on the interval ``[0, 1]``. - :ref:`int` **randi** **(** **)** -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). +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). :: @@ -1219,9 +1231,11 @@ Rounds ``s`` to the nearest whole number, with halfway cases rounded away from z :: - round(2.6) # Returns 3 + a = round(2.49) # a is 2.0 + a = round(2.5) # a is 3.0 + a = round(2.51) # a is 3.0 -See also :ref:`floor`, :ref:`ceil`, and :ref:`stepify`. +See also :ref:`floor`, :ref:`ceil`, :ref:`stepify`, and :ref:`int`. ---- @@ -1279,13 +1293,18 @@ Returns the hyperbolic sine of ``s``. .. _class_@GDScript_method_smoothstep: -- :ref:`float` **smoothstep** **(** :ref:`float` from, :ref:`float` to, :ref:`float` weight **)** +- :ref:`float` **smoothstep** **(** :ref:`float` from, :ref:`float` to, :ref:`float` s **)** -Returns a number smoothly interpolated between the ``from`` and ``to``, based on the ``weight``. Similar to :ref:`lerp`, but interpolates faster at the beginning and slower at the end. +Returns the result of smoothly interpolating the value of ``s`` between ``0`` and ``1``, based on the where ``s`` lies with respect to the edges ``from`` and ``to``. + +The return value is ``0`` if ``s <= from``, and ``1`` if ``s >= to``. If ``s`` lies between ``from`` and ``to``, the returned value follows an S-shaped curve that maps ``s`` between ``0`` and ``1``. + +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)``. :: - smoothstep(0, 2, 0.5) # Returns 0.15 + smoothstep(0, 2, -5.0) # Returns 0.0 + smoothstep(0, 2, 0.5) # Returns 0.15625 smoothstep(0, 2, 1.0) # Returns 0.5 smoothstep(0, 2, 2.0) # Returns 1.0 @@ -1301,7 +1320,7 @@ Returns the square root of ``s``, where ``s`` is a non-negative number. sqrt(9) # Returns 3 -If you need negative inputs, use ``System.Numerics.Complex`` in C#. +**Note:** Negative values of ``s`` return NaN. If you need negative inputs, use ``System.Numerics.Complex`` in C#. ---- @@ -1313,12 +1332,9 @@ Returns the position of the first non-zero digit, after the decimal point. Note :: - # n is 0 - n = step_decimals(5) - # n is 4 - n = step_decimals(1.0005) - # n is 9 - n = step_decimals(0.000000005) + n = step_decimals(5) # n is 0 + n = step_decimals(1.0005) # n is 4 + n = step_decimals(0.000000005) # n is 9 ---- @@ -1330,10 +1346,10 @@ Snaps float value ``s`` to a given ``step``. This can also be used to round a fl :: - stepify(100, 32) # Returns 96 + stepify(100, 32) # Returns 96.0 stepify(3.14159, 0.01) # Returns 3.14 -See also :ref:`ceil`, :ref:`floor`, and :ref:`round`. +See also :ref:`ceil`, :ref:`floor`, :ref:`round`, and :ref:`int`. ---- @@ -1341,7 +1357,7 @@ See also :ref:`ceil`, :ref:`floor` **str** **(** ... **)** |vararg| -Converts one or more arguments to string in the best way possible. +Converts one or more arguments of any type to string in the best way possible. :: @@ -1386,8 +1402,8 @@ Returns the hyperbolic tangent of ``s``. :: - a = log(2.0) # Returns 0.693147 - tanh(a) # Returns 0.6 + a = log(2.0) # a is 0.693147 + b = tanh(a) # b is 0.6 ---- diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index a42aeb725..257e14406 100644 --- a/classes/class_@globalscope.rst +++ b/classes/class_@globalscope.rst @@ -34,8 +34,6 @@ Properties +---------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :ref:`Geometry` | :ref:`Geometry` | +---------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| :ref:`GodotSharp` | :ref:`GodotSharp` | -+---------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :ref:`IP` | :ref:`IP` | +---------------------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :ref:`Input` | :ref:`Input` | @@ -1284,6 +1282,18 @@ enum **ButtonList**: .. _class_@GlobalScope_constant_JOY_BUTTON_15: +.. _class_@GlobalScope_constant_JOY_BUTTON_16: + +.. _class_@GlobalScope_constant_JOY_BUTTON_17: + +.. _class_@GlobalScope_constant_JOY_BUTTON_18: + +.. _class_@GlobalScope_constant_JOY_BUTTON_19: + +.. _class_@GlobalScope_constant_JOY_BUTTON_20: + +.. _class_@GlobalScope_constant_JOY_BUTTON_21: + .. _class_@GlobalScope_constant_JOY_BUTTON_MAX: .. _class_@GlobalScope_constant_JOY_SONY_CIRCLE: @@ -1336,6 +1346,18 @@ enum **ButtonList**: .. _class_@GlobalScope_constant_JOY_DPAD_RIGHT: +.. _class_@GlobalScope_constant_JOY_MISC1: + +.. _class_@GlobalScope_constant_JOY_PADDLE1: + +.. _class_@GlobalScope_constant_JOY_PADDLE2: + +.. _class_@GlobalScope_constant_JOY_PADDLE3: + +.. _class_@GlobalScope_constant_JOY_PADDLE4: + +.. _class_@GlobalScope_constant_JOY_TOUCHPAD: + .. _class_@GlobalScope_constant_JOY_L: .. _class_@GlobalScope_constant_JOY_L2: @@ -1426,7 +1448,19 @@ enum **JoystickList**: - **JOY_BUTTON_15** = **15** --- Gamepad button 15. -- **JOY_BUTTON_MAX** = **16** --- Represents the maximum number of joystick buttons supported. +- **JOY_BUTTON_16** = **16** --- Gamepad button 16. + +- **JOY_BUTTON_17** = **17** --- Gamepad button 17. + +- **JOY_BUTTON_18** = **18** --- Gamepad button 18. + +- **JOY_BUTTON_19** = **19** --- Gamepad button 19. + +- **JOY_BUTTON_20** = **20** --- Gamepad button 20. + +- **JOY_BUTTON_21** = **21** --- Gamepad button 21. + +- **JOY_BUTTON_MAX** = **22** --- Represents the maximum number of joystick buttons supported. - **JOY_SONY_CIRCLE** = **1** --- DualShock circle button. @@ -1478,6 +1512,18 @@ enum **JoystickList**: - **JOY_DPAD_RIGHT** = **15** --- Gamepad DPad right. +- **JOY_MISC1** = **16** --- Gamepad SDL miscellaneous button. + +- **JOY_PADDLE1** = **17** --- Gamepad SDL paddle 1 button. + +- **JOY_PADDLE2** = **18** --- Gamepad SDL paddle 2 button. + +- **JOY_PADDLE3** = **19** --- Gamepad SDL paddle 3 button. + +- **JOY_PADDLE4** = **20** --- Gamepad SDL paddle 4 button. + +- **JOY_TOUCHPAD** = **21** --- Gamepad SDL touchpad button. + - **JOY_L** = **4** --- Gamepad left Shoulder button. - **JOY_L2** = **6** --- Gamepad left trigger. @@ -1678,10 +1724,10 @@ Since :ref:`OK` has value 0, and all other failu var err = method_that_returns_error() if err != OK: - print("Failure!) + print("Failure!") # Or, equivalent: if err: - print("Still failing!) + print("Still failing!") - **FAILED** = **1** --- Generic error. @@ -2263,14 +2309,6 @@ The :ref:`Geometry` singleton. ---- -.. _class_@GlobalScope_property_GodotSharp: - -- :ref:`GodotSharp` **GodotSharp** - -The :ref:`GodotSharp` singleton. - ----- - .. _class_@GlobalScope_property_IP: - :ref:`IP` **IP** diff --git a/classes/class_aabb.rst b/classes/class_aabb.rst index 96a227d5b..4ffa98413 100644 --- a/classes/class_aabb.rst +++ b/classes/class_aabb.rst @@ -14,13 +14,21 @@ Axis-Aligned Bounding Box. Description ----------- -AABB consists of a position, a size, and several utility functions. It is typically used for fast overlap tests. +``AABB`` consists of a position, a size, and several utility functions. It is typically used for fast overlap tests. + +It uses floating-point coordinates. The 2D counterpart to ``AABB`` is :ref:`Rect2`. + +**Note:** Unlike :ref:`Rect2`, ``AABB`` does not have a variant that uses integer coordinates. Tutorials --------- - :doc:`../tutorials/math/index` +- :doc:`../tutorials/math/vector_math` + +- :doc:`../tutorials/math/vectors_advanced` + Properties ---------- @@ -118,7 +126,7 @@ Beginning corner. Typically has values lower than :ref:`end` to :ref:`end`. Typically all components are positive. +Size from :ref:`position` to :ref:`end`. Typically, all components are positive. If the size is negative, you can use :ref:`abs` to fix it. diff --git a/classes/class_animatedsprite.rst b/classes/class_animatedsprite.rst index 7fbcada43..fc540f3ad 100644 --- a/classes/class_animatedsprite.rst +++ b/classes/class_animatedsprite.rst @@ -25,6 +25,8 @@ Tutorials - :doc:`../tutorials/2d/2d_sprite_animation` +- `https://godotengine.org/asset-library/asset/515 `_ + Properties ---------- diff --git a/classes/class_animatedsprite3d.rst b/classes/class_animatedsprite3d.rst index e416749fc..14f43c212 100644 --- a/classes/class_animatedsprite3d.rst +++ b/classes/class_animatedsprite3d.rst @@ -50,6 +50,14 @@ Methods Signals ------- +.. _class_AnimatedSprite3D_signal_animation_finished: + +- **animation_finished** **(** **)** + +Emitted when the animation is finished (when it plays the last frame). If the animation is looping, this signal is emitted every time the last frame is drawn. + +---- + .. _class_AnimatedSprite3D_signal_frame_changed: - **frame_changed** **(** **)** diff --git a/classes/class_animation.rst b/classes/class_animation.rst index f67aea8b5..d444f1bb5 100644 --- a/classes/class_animation.rst +++ b/classes/class_animation.rst @@ -164,6 +164,8 @@ Methods +------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`UpdateMode` | :ref:`value_track_get_update_mode` **(** :ref:`int` track_idx **)** |const| | +------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`value_track_interpolate` **(** :ref:`int` track_idx, :ref:`float` time_sec **)** |const| | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`value_track_set_update_mode` **(** :ref:`int` track_idx, :ref:`UpdateMode` mode **)** | +------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -280,7 +282,7 @@ The total length of the animation (in seconds). | *Getter* | has_loop() | +-----------+-----------------+ -A flag indicating that the animation must loop. This is uses for correct interpolation of animation cycles, and for hinting the player that it must restart the animation. +A flag indicating that the animation must loop. This is used for correct interpolation of animation cycles, and for hinting the player that it must restart the animation. ---- @@ -391,7 +393,7 @@ Sets the start offset of the key identified by ``key_idx`` to value ``offset``. - void **audio_track_set_key_stream** **(** :ref:`int` track_idx, :ref:`int` key_idx, :ref:`Resource` stream **)** -Sets the stream of the key identified by ``key_idx`` to value ``offset``. The ``track_idx`` must be the index of an Audio Track. +Sets the stream of the key identified by ``key_idx`` to value ``stream``. The ``track_idx`` must be the index of an Audio Track. ---- @@ -767,6 +769,14 @@ Returns the update mode of a value track. ---- +.. _class_Animation_method_value_track_interpolate: + +- :ref:`Variant` **value_track_interpolate** **(** :ref:`int` track_idx, :ref:`float` time_sec **)** |const| + +Returns the interpolated value at the given time (in seconds). The ``track_idx`` must be the index of a value track. + +---- + .. _class_Animation_method_value_track_set_update_mode: - void **value_track_set_update_mode** **(** :ref:`int` track_idx, :ref:`UpdateMode` mode **)** diff --git a/classes/class_animationnodeadd3.rst b/classes/class_animationnodeadd3.rst index a3f4cd3ab..7020fa342 100644 --- a/classes/class_animationnodeadd3.rst +++ b/classes/class_animationnodeadd3.rst @@ -31,6 +31,8 @@ Tutorials - :doc:`../tutorials/animation/animation_tree` +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_animationnodeanimation.rst b/classes/class_animationnodeanimation.rst index 730ca765d..68c3a0042 100644 --- a/classes/class_animationnodeanimation.rst +++ b/classes/class_animationnodeanimation.rst @@ -23,6 +23,10 @@ Tutorials - :doc:`../tutorials/animation/animation_tree` +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_animationnodeblend2.rst b/classes/class_animationnodeblend2.rst index 789cfdd5b..1787f74c1 100644 --- a/classes/class_animationnodeblend2.rst +++ b/classes/class_animationnodeblend2.rst @@ -23,6 +23,10 @@ Tutorials - :doc:`../tutorials/animation/animation_tree` +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_animationnodeblendspace2d.rst b/classes/class_animationnodeblendspace2d.rst index 27c56981e..fd6efff39 100644 --- a/classes/class_animationnodeblendspace2d.rst +++ b/classes/class_animationnodeblendspace2d.rst @@ -27,6 +27,8 @@ Tutorials - :doc:`../tutorials/animation/animation_tree` +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_animationnodeoneshot.rst b/classes/class_animationnodeoneshot.rst index b64304ac2..a4bae9caa 100644 --- a/classes/class_animationnodeoneshot.rst +++ b/classes/class_animationnodeoneshot.rst @@ -23,6 +23,8 @@ Tutorials - :doc:`../tutorials/animation/animation_tree` +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_animationnodeoutput.rst b/classes/class_animationnodeoutput.rst index b4135fce8..9c065af3f 100644 --- a/classes/class_animationnodeoutput.rst +++ b/classes/class_animationnodeoutput.rst @@ -18,6 +18,10 @@ Tutorials - :doc:`../tutorials/animation/animation_tree` +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_animationnodestatemachineplayback.rst b/classes/class_animationnodestatemachineplayback.rst index 60decaf41..3f7e4f4ed 100644 --- a/classes/class_animationnodestatemachineplayback.rst +++ b/classes/class_animationnodestatemachineplayback.rst @@ -40,23 +40,33 @@ Properties Methods ------- -+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_current_node` **(** **)** |const| | -+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| :ref:`PoolStringArray` | :ref:`get_travel_path` **(** **)** |const| | -+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_playing` **(** **)** |const| | -+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`start` **(** :ref:`String` node **)** | -+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`stop` **(** **)** | -+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`travel` **(** :ref:`String` to_node **)** | -+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ ++-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`get_current_length` **(** **)** |const| | ++-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_current_node` **(** **)** |const| | ++-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`get_current_play_position` **(** **)** |const| | ++-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PoolStringArray` | :ref:`get_travel_path` **(** **)** |const| | ++-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`is_playing` **(** **)** |const| | ++-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`start` **(** :ref:`String` node **)** | ++-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`stop` **(** **)** | ++-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`travel` **(** :ref:`String` to_node **)** | ++-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------+ Method Descriptions ------------------- +.. _class_AnimationNodeStateMachinePlayback_method_get_current_length: + +- :ref:`float` **get_current_length** **(** **)** |const| + +---- + .. _class_AnimationNodeStateMachinePlayback_method_get_current_node: - :ref:`String` **get_current_node** **(** **)** |const| @@ -65,6 +75,14 @@ Returns the currently playing animation state. ---- +.. _class_AnimationNodeStateMachinePlayback_method_get_current_play_position: + +- :ref:`float` **get_current_play_position** **(** **)** |const| + +Returns the playback position within the current animation state. + +---- + .. _class_AnimationNodeStateMachinePlayback_method_get_travel_path: - :ref:`PoolStringArray` **get_travel_path** **(** **)** |const| diff --git a/classes/class_animationnodestatemachinetransition.rst b/classes/class_animationnodestatemachinetransition.rst index 096727e65..4c50111ac 100644 --- a/classes/class_animationnodestatemachinetransition.rst +++ b/classes/class_animationnodestatemachinetransition.rst @@ -78,7 +78,7 @@ Property Descriptions | *Getter* | get_advance_condition() | +-----------+------------------------------+ -Turn on auto advance when this condition is set. The provided name will become a boolean parameter on the :ref:`AnimationTree` that can be controlled from code (see `https://docs.godotengine.org/en/latest/tutorials/animation/animation_tree.html#controlling-from-code `_). For example, if :ref:`AnimationTree.tree_root` is an :ref:`AnimationNodeStateMachine` and :ref:`advance_condition` is set to ``"idle"``: +Turn on auto advance when this condition is set. The provided name will become a boolean parameter on the :ref:`AnimationTree` that can be controlled from code (see `https://docs.godotengine.org/en/3.3/tutorials/animation/animation_tree.html#controlling-from-code `_). For example, if :ref:`AnimationTree.tree_root` is an :ref:`AnimationNodeStateMachine` and :ref:`advance_condition` is set to ``"idle"``: :: diff --git a/classes/class_animationnodetimescale.rst b/classes/class_animationnodetimescale.rst index 660c17993..e09a2e73b 100644 --- a/classes/class_animationnodetimescale.rst +++ b/classes/class_animationnodetimescale.rst @@ -23,6 +23,8 @@ Tutorials - :doc:`../tutorials/animation/animation_tree` +- `https://godotengine.org/asset-library/asset/125 `_ + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_animationnodetransition.rst b/classes/class_animationnodetransition.rst index ed1ba133b..b2a04a706 100644 --- a/classes/class_animationnodetransition.rst +++ b/classes/class_animationnodetransition.rst @@ -23,6 +23,10 @@ Tutorials - :doc:`../tutorials/animation/animation_tree` +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_animationplayer.rst b/classes/class_animationplayer.rst index fb3e3b63a..3711d4e78 100644 --- a/classes/class_animationplayer.rst +++ b/classes/class_animationplayer.rst @@ -25,11 +25,11 @@ Updating the target properties of animations occurs at process time. Tutorials --------- -- :doc:`../getting_started/step_by_step/animations` +- :doc:`../tutorials/animation/index` - :doc:`../tutorials/2d/2d_sprite_animation` -- :doc:`../tutorials/animation/index` +- `https://godotengine.org/asset-library/asset/678 `_ Properties ---------- @@ -220,7 +220,7 @@ The name of the animation to play when the scene loads. The name 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`. +**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`. ---- diff --git a/classes/class_animationtree.rst b/classes/class_animationtree.rst index 9bd115122..b4f25287c 100644 --- a/classes/class_animationtree.rst +++ b/classes/class_animationtree.rst @@ -23,7 +23,7 @@ Tutorials - :doc:`../tutorials/animation/animation_tree` -- `https://github.com/godotengine/tps-demo `_ +- `https://godotengine.org/asset-library/asset/678 `_ Properties ---------- diff --git a/classes/class_area.rst b/classes/class_area.rst index 883f82e80..6f8ab66fc 100644 --- a/classes/class_area.rst +++ b/classes/class_area.rst @@ -18,6 +18,13 @@ Description 3D area that detects :ref:`CollisionObject` nodes overlapping, entering, or exiting. Can also alter or override local physics parameters (gravity, damping). +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/127 `_ + Properties ---------- @@ -87,7 +94,9 @@ Signals - **area_entered** **(** :ref:`Area` area **)** -Emitted when another area enters. +Emitted when another Area enters this Area. Requires :ref:`monitoring` to be set to ``true``. + +``area`` the other Area. ---- @@ -95,23 +104,41 @@ Emitted when another area enters. - **area_exited** **(** :ref:`Area` area **)** -Emitted when another area exits. +Emitted when another Area exits this Area. Requires :ref:`monitoring` to be set to ``true``. + +``area`` the other Area. ---- .. _class_Area_signal_area_shape_entered: -- **area_shape_entered** **(** :ref:`int` area_id, :ref:`Area` area, :ref:`int` area_shape, :ref:`int` self_shape **)** +- **area_shape_entered** **(** :ref:`int` area_id, :ref:`Area` area, :ref:`int` area_shape, :ref:`int` local_shape **)** -Emitted when another area enters, reporting which areas overlapped. ``shape_owner_get_owner(shape_find_owner(shape))`` returns the parent object of the owner of the ``shape``. +Emitted when one of another Area's :ref:`Shape`\ s enters one of this Area's :ref:`Shape`\ s. Requires :ref:`monitoring` to be set to ``true``. + +``area_id`` the :ref:`RID` of the other Area's :ref:`CollisionObject` used by the :ref:`PhysicsServer`. + +``area`` the other Area. + +``area_shape`` the index of the :ref:`Shape` of the other Area used by the :ref:`PhysicsServer`. + +``local_shape`` the index of the :ref:`Shape` of this Area used by the :ref:`PhysicsServer`. ---- .. _class_Area_signal_area_shape_exited: -- **area_shape_exited** **(** :ref:`int` area_id, :ref:`Area` area, :ref:`int` area_shape, :ref:`int` self_shape **)** +- **area_shape_exited** **(** :ref:`int` area_id, :ref:`Area` area, :ref:`int` area_shape, :ref:`int` local_shape **)** -Emitted when another area exits, reporting which areas were overlapping. +Emitted when one of another Area's :ref:`Shape`\ s enters one of this Area's :ref:`Shape`\ s. Requires :ref:`monitoring` to be set to ``true``. + +``area_id`` the :ref:`RID` of the other Area's :ref:`CollisionObject` used by the :ref:`PhysicsServer`. + +``area`` the other Area. + +``area_shape`` the index of the :ref:`Shape` of the other Area used by the :ref:`PhysicsServer`. + +``local_shape`` the index of the :ref:`Shape` of this Area used by the :ref:`PhysicsServer`. ---- @@ -119,9 +146,9 @@ Emitted when another area exits, reporting which areas were overlapping. - **body_entered** **(** :ref:`Node` body **)** -Emitted when a physics body enters. +Emitted when a :ref:`PhysicsBody` or :ref:`GridMap` enters this Area. Requires :ref:`monitoring` to be set to ``true``. :ref:`GridMap`\ s are detected if the :ref:`MeshLibrary` has Collision :ref:`Shape`\ s. -The ``body`` argument can either be a :ref:`PhysicsBody` or a :ref:`GridMap` instance (while GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). +``body`` the :ref:`Node`, if it exists in the tree, of the other :ref:`PhysicsBody` or :ref:`GridMap`. ---- @@ -129,29 +156,41 @@ The ``body`` argument can either be a :ref:`PhysicsBody` or a - **body_exited** **(** :ref:`Node` body **)** -Emitted when a physics body exits. +Emitted when a :ref:`PhysicsBody` or :ref:`GridMap` exits this Area. Requires :ref:`monitoring` to be set to ``true``. :ref:`GridMap`\ s are detected if the :ref:`MeshLibrary` has Collision :ref:`Shape`\ s. -The ``body`` argument can either be a :ref:`PhysicsBody` or a :ref:`GridMap` instance (while GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). +``body`` the :ref:`Node`, if it exists in the tree, of the other :ref:`PhysicsBody` or :ref:`GridMap`. ---- .. _class_Area_signal_body_shape_entered: -- **body_shape_entered** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` area_shape **)** +- **body_shape_entered** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` local_shape **)** -Emitted when a physics body enters, reporting which shapes overlapped. +Emitted when one of a :ref:`PhysicsBody` or :ref:`GridMap`'s :ref:`Shape`\ s enters one of this Area's :ref:`Shape`\ s. Requires :ref:`monitoring` to be set to ``true``. :ref:`GridMap`\ s are detected if the :ref:`MeshLibrary` has Collision :ref:`Shape`\ s. -The ``body`` argument can either be a :ref:`PhysicsBody` or a :ref:`GridMap` instance (while GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). +``body_id`` the :ref:`RID` of the :ref:`PhysicsBody` or :ref:`MeshLibrary`'s :ref:`CollisionObject` used by the :ref:`PhysicsServer`. + +``body`` the :ref:`Node`, if it exists in the tree, of the :ref:`PhysicsBody` or :ref:`GridMap`. + +``body_shape`` the index of the :ref:`Shape` of the :ref:`PhysicsBody` or :ref:`GridMap` used by the :ref:`PhysicsServer`. + +``local_shape`` the index of the :ref:`Shape` of this Area used by the :ref:`PhysicsServer`. ---- .. _class_Area_signal_body_shape_exited: -- **body_shape_exited** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` area_shape **)** +- **body_shape_exited** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` local_shape **)** -Emitted when a physics body exits, reporting which shapes were overlapping. +Emitted when one of a :ref:`PhysicsBody` or :ref:`GridMap`'s :ref:`Shape`\ s enters one of this Area's :ref:`Shape`\ s. Requires :ref:`monitoring` to be set to ``true``. :ref:`GridMap`\ s are detected if the :ref:`MeshLibrary` has Collision :ref:`Shape`\ s. -The ``body`` argument can either be a :ref:`PhysicsBody` or a :ref:`GridMap` instance (while GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). +``body_id`` the :ref:`RID` of the :ref:`PhysicsBody` or :ref:`MeshLibrary`'s :ref:`CollisionObject` used by the :ref:`PhysicsServer`. + +``body`` the :ref:`Node`, if it exists in the tree, of the :ref:`PhysicsBody` or :ref:`GridMap`. + +``body_shape`` the index of the :ref:`Shape` of the :ref:`PhysicsBody` or :ref:`GridMap` used by the :ref:`PhysicsServer`. + +``local_shape`` the index of the :ref:`Shape` of this Area used by the :ref:`PhysicsServer`. Enumerations ------------ @@ -195,7 +234,9 @@ Property Descriptions | *Getter* | get_angular_damp() | +-----------+-------------------------+ -The rate at which objects stop spinning in this area. Represents the angular velocity lost per second. Values range from ``0`` (no damping) to ``1`` (full damping). +The rate at which objects stop spinning in this area. Represents the angular velocity lost per second. + +See :ref:`ProjectSettings.physics/3d/default_angular_damp` for more details about damping. ---- @@ -243,7 +284,7 @@ If ``true``, the area's audio bus overrides the default audio bus. | *Getter* | get_collision_layer() | +-----------+----------------------------+ -The area's physics layer(s). Collidable objects can exist in any of 32 different layers. A contact is detected if object A is in any of the layers that object B scans, or object B is in any layers that object A scans. See also :ref:`collision_mask`. See `Collision layers and masks `_ in the documentation for more information. +The area's physics layer(s). Collidable objects can exist in any of 32 different layers. A contact is detected if object A is in any of the layers that object B scans, or object B is in any layers that object A scans. See also :ref:`collision_mask`. See `Collision layers and masks `_ in the documentation for more information. ---- @@ -259,7 +300,7 @@ The area's physics layer(s). Collidable objects can exist in any of 32 different | *Getter* | get_collision_mask() | +-----------+---------------------------+ -The physics layers this area scans to determine collision detection. See `Collision layers and masks `_ in the documentation for more information. +The physics layers this area scans to determine collision detection. See `Collision layers and masks `_ in the documentation for more information. ---- @@ -339,7 +380,9 @@ The area's gravity vector (not normalized). If gravity is a point (see :ref:`gra | *Getter* | get_linear_damp() | +-----------+------------------------+ -The rate at which objects stop moving in this area. Represents the linear velocity lost per second. Values range from ``0`` (no damping) to ``1`` (full damping). +The rate at which objects stop moving in this area. Represents the linear velocity lost per second. + +See :ref:`ProjectSettings.physics/3d/default_linear_damp` for more details about damping. ---- diff --git a/classes/class_area2d.rst b/classes/class_area2d.rst index b0f0ee70e..e303486b8 100644 --- a/classes/class_area2d.rst +++ b/classes/class_area2d.rst @@ -23,6 +23,12 @@ Tutorials - :doc:`../tutorials/physics/using_area_2d` +- `https://godotengine.org/asset-library/asset/515 `_ + +- `https://godotengine.org/asset-library/asset/121 `_ + +- `https://godotengine.org/asset-library/asset/120 `_ + Properties ---------- @@ -84,7 +90,9 @@ Signals - **area_entered** **(** :ref:`Area2D` area **)** -Emitted when another area enters. +Emitted when another Area2D enters this Area2D. Requires :ref:`monitoring` to be set to ``true``. + +``area`` the other Area2D. ---- @@ -92,23 +100,41 @@ Emitted when another area enters. - **area_exited** **(** :ref:`Area2D` area **)** -Emitted when another area exits. +Emitted when another Area2D exits this Area2D. Requires :ref:`monitoring` to be set to ``true``. + +``area`` the other Area2D. ---- .. _class_Area2D_signal_area_shape_entered: -- **area_shape_entered** **(** :ref:`int` area_id, :ref:`Area2D` area, :ref:`int` area_shape, :ref:`int` self_shape **)** +- **area_shape_entered** **(** :ref:`int` area_id, :ref:`Area2D` area, :ref:`int` area_shape, :ref:`int` local_shape **)** -Emitted when another area enters, reporting which shapes overlapped. ``shape_owner_get_owner(shape_find_owner(shape))`` returns the parent object of the owner of the ``shape``. +Emitted when one of another Area2D's :ref:`Shape2D`\ s enters one of this Area2D's :ref:`Shape2D`\ s. Requires :ref:`monitoring` to be set to ``true``. + +``area_id`` the :ref:`RID` of the other Area2D's :ref:`CollisionObject2D` used by the :ref:`Physics2DServer`. + +``area`` the other Area2D. + +``area_shape`` the index of the :ref:`Shape2D` of the other Area2D used by the :ref:`Physics2DServer`. + +``local_shape`` the index of the :ref:`Shape2D` of this Area2D used by the :ref:`Physics2DServer`. ---- .. _class_Area2D_signal_area_shape_exited: -- **area_shape_exited** **(** :ref:`int` area_id, :ref:`Area2D` area, :ref:`int` area_shape, :ref:`int` self_shape **)** +- **area_shape_exited** **(** :ref:`int` area_id, :ref:`Area2D` area, :ref:`int` area_shape, :ref:`int` local_shape **)** -Emitted when another area exits, reporting which shapes were overlapping. +Emitted when one of another Area2D's :ref:`Shape2D`\ s exits one of this Area2D's :ref:`Shape2D`\ s. Requires :ref:`monitoring` to be set to ``true``. + +``area_id`` the :ref:`RID` of the other Area2D's :ref:`CollisionObject2D` used by the :ref:`Physics2DServer`. + +``area`` the other Area2D. + +``area_shape`` the index of the :ref:`Shape2D` of the other Area2D used by the :ref:`Physics2DServer`. + +``local_shape`` the index of the :ref:`Shape2D` of this Area2D used by the :ref:`Physics2DServer`. ---- @@ -116,9 +142,9 @@ Emitted when another area exits, reporting which shapes were overlapping. - **body_entered** **(** :ref:`Node` body **)** -Emitted when a physics body enters. +Emitted when a :ref:`PhysicsBody2D` or :ref:`TileMap` enters this Area2D. Requires :ref:`monitoring` to be set to ``true``. :ref:`TileMap`\ s are detected if the :ref:`TileSet` has Collision :ref:`Shape2D`\ s. -The ``body`` argument can either be a :ref:`PhysicsBody2D` or a :ref:`TileMap` instance (while TileMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). +``body`` the :ref:`Node`, if it exists in the tree, of the other :ref:`PhysicsBody2D` or :ref:`TileMap`. ---- @@ -126,29 +152,41 @@ The ``body`` argument can either be a :ref:`PhysicsBody2D` - **body_exited** **(** :ref:`Node` body **)** -Emitted when a physics body exits. +Emitted when a :ref:`PhysicsBody2D` or :ref:`TileMap` exits this Area2D. Requires :ref:`monitoring` to be set to ``true``. :ref:`TileMap`\ s are detected if the :ref:`TileSet` has Collision :ref:`Shape2D`\ s. -The ``body`` argument can either be a :ref:`PhysicsBody2D` or a :ref:`TileMap` instance (while TileMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). +``body`` the :ref:`Node`, if it exists in the tree, of the other :ref:`PhysicsBody2D` or :ref:`TileMap`. ---- .. _class_Area2D_signal_body_shape_entered: -- **body_shape_entered** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` area_shape **)** +- **body_shape_entered** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` local_shape **)** -Emitted when a physics body enters, reporting which shapes overlapped. +Emitted when one of a :ref:`PhysicsBody2D` or :ref:`TileMap`'s :ref:`Shape2D`\ s enters one of this Area2D's :ref:`Shape2D`\ s. Requires :ref:`monitoring` to be set to ``true``. :ref:`TileMap`\ s are detected if the :ref:`TileSet` has Collision :ref:`Shape2D`\ s. -The ``body`` argument can either be a :ref:`PhysicsBody2D` or a :ref:`TileMap` instance (while TileMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). +``body_id`` the :ref:`RID` of the :ref:`PhysicsBody2D` or :ref:`TileSet`'s :ref:`CollisionObject2D` used by the :ref:`Physics2DServer`. + +``body`` the :ref:`Node`, if it exists in the tree, of the :ref:`PhysicsBody2D` or :ref:`TileMap`. + +``body_shape`` the index of the :ref:`Shape2D` of the :ref:`PhysicsBody2D` or :ref:`TileMap` used by the :ref:`Physics2DServer`. + +``local_shape`` the index of the :ref:`Shape2D` of this Area2D used by the :ref:`Physics2DServer`. ---- .. _class_Area2D_signal_body_shape_exited: -- **body_shape_exited** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` area_shape **)** +- **body_shape_exited** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` local_shape **)** -Emitted when a physics body exits, reporting which shapes were overlapping. +Emitted when one of a :ref:`PhysicsBody2D` or :ref:`TileMap`'s :ref:`Shape2D`\ s exits one of this Area2D's :ref:`Shape2D`\ s. Requires :ref:`monitoring` to be set to ``true``. :ref:`TileMap`\ s are detected if the :ref:`TileSet` has Collision :ref:`Shape2D`\ s. -The ``body`` argument can either be a :ref:`PhysicsBody2D` or a :ref:`TileMap` instance (while TileMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body). +``body_id`` the :ref:`RID` of the :ref:`PhysicsBody2D` or :ref:`TileSet`'s :ref:`CollisionObject2D` used by the :ref:`Physics2DServer`. + +``body`` the :ref:`Node`, if it exists in the tree, of the :ref:`PhysicsBody2D` or :ref:`TileMap`. + +``body_shape`` the index of the :ref:`Shape2D` of the :ref:`PhysicsBody2D` or :ref:`TileMap` used by the :ref:`Physics2DServer`. + +``local_shape`` the index of the :ref:`Shape2D` of this Area2D used by the :ref:`Physics2DServer`. Enumerations ------------ @@ -192,7 +230,9 @@ Property Descriptions | *Getter* | get_angular_damp() | +-----------+-------------------------+ -The rate at which objects stop spinning in this area. Represents the angular velocity lost per second. Values range from ``0`` (no damping) to ``1`` (full damping). +The rate at which objects stop spinning in this area. Represents the angular velocity lost per second. + +See :ref:`ProjectSettings.physics/2d/default_angular_damp` for more details about damping. ---- @@ -240,7 +280,7 @@ If ``true``, the area's audio bus overrides the default audio bus. | *Getter* | get_collision_layer() | +-----------+----------------------------+ -The area's physics layer(s). Collidable objects can exist in any of 32 different layers. A contact is detected if object A is in any of the layers that object B scans, or object B is in any layers that object A scans. See also :ref:`collision_mask`. See `Collision layers and masks `_ in the documentation for more information. +The area's physics layer(s). Collidable objects can exist in any of 32 different layers. A contact is detected if object A is in any of the layers that object B scans, or object B is in any layers that object A scans. See also :ref:`collision_mask`. See `Collision layers and masks `_ in the documentation for more information. ---- @@ -256,7 +296,7 @@ The area's physics layer(s). Collidable objects can exist in any of 32 different | *Getter* | get_collision_mask() | +-----------+---------------------------+ -The physics layers this area scans to determine collision detection. See `Collision layers and masks `_ in the documentation for more information. +The physics layers this area scans to determine collision detection. See `Collision layers and masks `_ in the documentation for more information. ---- @@ -336,7 +376,9 @@ The area's gravity vector (not normalized). If gravity is a point (see :ref:`gra | *Getter* | get_linear_damp() | +-----------+------------------------+ -The rate at which objects stop moving in this area. Represents the linear velocity lost per second. Values range from ``0`` (no damping) to ``1`` (full damping). +The rate at which objects stop moving in this area. Represents the linear velocity lost per second. + +See :ref:`ProjectSettings.physics/2d/default_linear_damp` for more details about damping. ---- diff --git a/classes/class_array.rst b/classes/class_array.rst index 5c882b398..7213ca17a 100644 --- a/classes/class_array.rst +++ b/classes/class_array.rst @@ -35,8 +35,12 @@ Arrays can be concatenated using the ``+`` operator: var array2 = [3, "Four"] print(array1 + array2) # ["One", 2, 3, "Four"] +**Note:** Concatenating with the ``+=`` operator will create a new array, which has a cost. If you want to append another array to an existing array, :ref:`append_array` is more efficient. + **Note:** Arrays are always passed by reference. To get a copy of an array which can be modified independently of the original array, use :ref:`duplicate`. +**Note:** When declaring an array with ``const``, the array itself can still be mutated by defining the values at individual indices or pushing/removing elements. Using ``const`` will only prevent assigning the constant with another value after it was initialized. + Methods ------- @@ -57,6 +61,8 @@ Methods +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`append` **(** :ref:`Variant` value **)** | +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`append_array` **(** :ref:`Array` array **)** | ++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`back` **(** **)** | +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`bsearch` **(** :ref:`Variant` value, :ref:`bool` before=true **)** | @@ -171,6 +177,21 @@ Appends an element at the end of the array (alias of :ref:`push_back` 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]. + +---- + .. _class_Array_method_back: - :ref:`Variant` **back** **(** **)** @@ -195,9 +216,32 @@ Finds the index of an existing value (or the insertion index that maintains sort - :ref:`int` **bsearch_custom** **(** :ref:`Variant` value, :ref:`Object` obj, :ref:`String` func, :ref:`bool` before=true **)** -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. +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 declared in the ``obj``. 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. -**Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. +:: + + func cardinal_to_algebraic(a): + match a: + "one": + return 1 + "two": + return 2 + "three": + return 3 + "four": + return 4 + _: + return 0 + + func compare(a, b): + return cardinal_to_algebraic(a) < cardinal_to_algebraic(b) + + func _ready(): + var a = ["one", "two", "three", "four"] + # `compare` is defined in this object, so we use `self` as the `obj` parameter. + print(a.bsearch_custom("three", self, "compare", true)) # Expected value is 2. + +**Note:** Calling :ref:`bsearch_custom` on an unsorted array results in unexpected behavior. ---- @@ -239,7 +283,11 @@ Returns ``true`` if the array is empty. - void **erase** **(** :ref:`Variant` value **)** -Removes the first occurrence of a value from the array. +Removes the first occurrence of a value from the array. To remove an element by index, use :ref:`remove` instead. + +**Note:** This method acts in-place and doesn't return a value. + +**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. ---- @@ -296,7 +344,9 @@ Returns ``true`` if the array contains the given value. - :ref:`int` **hash** **(** **)** -Returns a hashed integer value representing the array contents. +Returns a hashed integer value representing the array and its contents. + +**Note:** Arrays with equal contents can still produce different hashes. Only the exact same arrays will produce the same hashed integer value. ---- @@ -306,6 +356,10 @@ Returns a hashed integer value representing the array contents. 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()``). +**Note:** This method acts in-place and doesn't return a value. + +**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. + ---- .. _class_Array_method_invert: @@ -336,7 +390,7 @@ Returns the minimum value contained in the array if all elements are of comparab - :ref:`Variant` **pop_back** **(** **)** -Removes and returns the last element of the array. Returns ``null`` if the array is empty, without printing an error message. +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`. ---- @@ -344,7 +398,9 @@ Removes and returns the last element of the array. Returns ``null`` if the array - :ref:`Variant` **pop_front** **(** **)** -Removes and returns the first element of the array. Returns ``null`` if the array is empty, wwithout printing an error message. +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`. + +**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. ---- @@ -352,7 +408,7 @@ Removes and returns the first element of the array. Returns ``null`` if the arra - void **push_back** **(** :ref:`Variant` value **)** -Appends an element at the end of the array. +Appends an element at the end of the array. See also :ref:`push_front`. ---- @@ -360,7 +416,9 @@ Appends an element at the end of the array. - void **push_front** **(** :ref:`Variant` value **)** -Adds an element at the beginning of the array. +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. ---- @@ -368,7 +426,11 @@ Adds an element at the beginning of the array. - void **remove** **(** :ref:`int` position **)** -Removes an element from the array by index. If the index does not exist in the array, nothing happens. +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. + +**Note:** This method acts in-place and doesn't return a value. + +**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. ---- diff --git a/classes/class_arvrinterface.rst b/classes/class_arvrinterface.rst index eba45143b..354121545 100644 --- a/classes/class_arvrinterface.rst +++ b/classes/class_arvrinterface.rst @@ -11,7 +11,7 @@ ARVRInterface **Inherits:** :ref:`Reference` **<** :ref:`Object` -**Inherited By:** :ref:`ARVRInterfaceGDNative`, :ref:`MobileVRInterface` +**Inherited By:** :ref:`ARVRInterfaceGDNative`, :ref:`MobileVRInterface`, :ref:`WebXRInterface` Base class for an AR/VR interface implementation. diff --git a/classes/class_aspectratiocontainer.rst b/classes/class_aspectratiocontainer.rst new file mode 100644 index 000000000..a8c25a7dc --- /dev/null +++ b/classes/class_aspectratiocontainer.rst @@ -0,0 +1,144 @@ +:github_url: hide + +.. Generated automatically by doc/tools/makerst.py in Godot's source tree. +.. DO NOT EDIT THIS FILE, but the AspectRatioContainer.xml source instead. +.. The source is found in doc/classes or modules//doc_classes. + +.. _class_AspectRatioContainer: + +AspectRatioContainer +==================== + +**Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` + +Container that preserves its child controls' aspect ratio. + +Description +----------- + +Arranges child controls in a way to preserve their aspect ratio automatically whenever the container is resized. Solves the problem where the container size is dynamic and the contents' size needs to adjust accordingly without losing proportions. + +Properties +---------- + ++-----------------------------------------------------------+---------------------------------------------------------------------------------------+---------+ +| :ref:`AlignMode` | :ref:`alignment_horizontal` | ``1`` | ++-----------------------------------------------------------+---------------------------------------------------------------------------------------+---------+ +| :ref:`AlignMode` | :ref:`alignment_vertical` | ``1`` | ++-----------------------------------------------------------+---------------------------------------------------------------------------------------+---------+ +| :ref:`float` | :ref:`ratio` | ``1.0`` | ++-----------------------------------------------------------+---------------------------------------------------------------------------------------+---------+ +| :ref:`StretchMode` | :ref:`stretch_mode` | ``2`` | ++-----------------------------------------------------------+---------------------------------------------------------------------------------------+---------+ + +Enumerations +------------ + +.. _enum_AspectRatioContainer_StretchMode: + +.. _class_AspectRatioContainer_constant_STRETCH_WIDTH_CONTROLS_HEIGHT: + +.. _class_AspectRatioContainer_constant_STRETCH_HEIGHT_CONTROLS_WIDTH: + +.. _class_AspectRatioContainer_constant_STRETCH_FIT: + +.. _class_AspectRatioContainer_constant_STRETCH_COVER: + +enum **StretchMode**: + +- **STRETCH_WIDTH_CONTROLS_HEIGHT** = **0** --- The height of child controls is automatically adjusted based on the width of the container. + +- **STRETCH_HEIGHT_CONTROLS_WIDTH** = **1** --- The width of child controls is automatically adjusted based on the height of the container. + +- **STRETCH_FIT** = **2** --- The bounding rectangle of child controls is automatically adjusted to fit inside the container while keeping the aspect ratio. + +- **STRETCH_COVER** = **3** --- The width and height of child controls is automatically adjusted to make their bounding rectangle cover the entire area of the container while keeping the aspect ratio. + +When the bounding rectangle of child controls exceed the container's size and :ref:`Control.rect_clip_content` is enabled, this allows to show only the container's area restricted by its own bounding rectangle. + +---- + +.. _enum_AspectRatioContainer_AlignMode: + +.. _class_AspectRatioContainer_constant_ALIGN_BEGIN: + +.. _class_AspectRatioContainer_constant_ALIGN_CENTER: + +.. _class_AspectRatioContainer_constant_ALIGN_END: + +enum **AlignMode**: + +- **ALIGN_BEGIN** = **0** --- Aligns child controls with the beginning (left or top) of the container. + +- **ALIGN_CENTER** = **1** --- Aligns child controls with the center of the container. + +- **ALIGN_END** = **2** --- Aligns child controls with the end (right or bottom) of the container. + +Property Descriptions +--------------------- + +.. _class_AspectRatioContainer_property_alignment_horizontal: + +- :ref:`AlignMode` **alignment_horizontal** + ++-----------+---------------------------------+ +| *Default* | ``1`` | ++-----------+---------------------------------+ +| *Setter* | set_alignment_horizontal(value) | ++-----------+---------------------------------+ +| *Getter* | get_alignment_horizontal() | ++-----------+---------------------------------+ + +Specifies the horizontal relative position of child controls. + +---- + +.. _class_AspectRatioContainer_property_alignment_vertical: + +- :ref:`AlignMode` **alignment_vertical** + ++-----------+-------------------------------+ +| *Default* | ``1`` | ++-----------+-------------------------------+ +| *Setter* | set_alignment_vertical(value) | ++-----------+-------------------------------+ +| *Getter* | get_alignment_vertical() | ++-----------+-------------------------------+ + +Specifies the vertical relative position of child controls. + +---- + +.. _class_AspectRatioContainer_property_ratio: + +- :ref:`float` **ratio** + ++-----------+------------------+ +| *Default* | ``1.0`` | ++-----------+------------------+ +| *Setter* | set_ratio(value) | ++-----------+------------------+ +| *Getter* | get_ratio() | ++-----------+------------------+ + +The aspect ratio to enforce on child controls. This is the width divided by the height. The ratio depends on the :ref:`stretch_mode`. + +---- + +.. _class_AspectRatioContainer_property_stretch_mode: + +- :ref:`StretchMode` **stretch_mode** + ++-----------+-------------------------+ +| *Default* | ``2`` | ++-----------+-------------------------+ +| *Setter* | set_stretch_mode(value) | ++-----------+-------------------------+ +| *Getter* | get_stretch_mode() | ++-----------+-------------------------+ + +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.)` +.. |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.)` diff --git a/classes/class_astar.rst b/classes/class_astar.rst index 70253903e..3865663a4 100644 --- a/classes/class_astar.rst +++ b/classes/class_astar.rst @@ -11,7 +11,7 @@ AStar **Inherits:** :ref:`Reference` **<** :ref:`Object` -An implementation of A\* to find shortest paths among connected points in space. +An implementation of A\* to find the shortest paths among connected points in space. Description ----------- @@ -35,6 +35,8 @@ It is also possible to use non-Euclidean distances. To do so, create a class tha :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 ``_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 to the sum of the :ref:`_compute_cost` results of all segments in the path multiplied by the ``weight_scale``\ s of the end points 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 to the sum of Euclidean distances of all segments in the path. + Methods ------- @@ -117,7 +119,9 @@ Note that this function is hidden in the default ``AStar`` class. - void **add_point** **(** :ref:`int` id, :ref:`Vector3` position, :ref:`float` weight_scale=1.0 **)** -Adds a new point at the given position with the given identifier. The algorithm prefers points with lower ``weight_scale`` to form a path. The ``id`` must be 0 or larger, and the ``weight_scale`` must be 1 or larger. +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 1 or larger. + +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. :: @@ -349,7 +353,7 @@ Sets the ``position`` for the point with the given ``id``. - void **set_point_weight_scale** **(** :ref:`int` id, :ref:`float` weight_scale **)** -Sets the ``weight_scale`` for the point with the given ``id``. +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.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_astar2d.rst b/classes/class_astar2d.rst index d273cf769..d700fab13 100644 --- a/classes/class_astar2d.rst +++ b/classes/class_astar2d.rst @@ -100,7 +100,9 @@ Note that this function is hidden in the default ``AStar2D`` class. - void **add_point** **(** :ref:`int` id, :ref:`Vector2` position, :ref:`float` weight_scale=1.0 **)** -Adds a new point at the given position with the given identifier. The algorithm prefers points with lower ``weight_scale`` to form a path. The ``id`` must be 0 or larger, and the ``weight_scale`` must be 1 or larger. +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 1 or larger. + +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. :: @@ -332,7 +334,7 @@ Sets the ``position`` for the point with the given ``id``. - void **set_point_weight_scale** **(** :ref:`int` id, :ref:`float` weight_scale **)** -Sets the ``weight_scale`` for the point with the given ``id``. +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.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_atlastexture.rst b/classes/class_atlastexture.rst index 120a25d0f..785a0059f 100644 --- a/classes/class_atlastexture.rst +++ b/classes/class_atlastexture.rst @@ -11,12 +11,16 @@ AtlasTexture **Inherits:** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` -Packs multiple small textures in a single, bigger one. Helps to optimize video memory costs and render calls. +Crops out one part of a texture, such as a texture from a texture atlas. Description ----------- -:ref:`Texture` resource aimed at managing big textures files that pack multiple smaller textures. Consists of a :ref:`Texture`, a margin that defines the border width, and a region that defines the actual area of the AtlasTexture. +:ref:`Texture` resource that crops out one part of the :ref:`atlas` texture, defined by :ref:`region`. The main use case is cropping out textures from a texture atlas, which is a big texture file that packs multiple smaller textures. Consists of a :ref:`Texture` for the :ref:`atlas`, a :ref:`region` that defines the area of :ref:`atlas` to use, and a :ref:`margin` that defines the border width. + +``AtlasTexture`` cannot be used in an :ref:`AnimatedTexture`, cannot be tiled in nodes such as :ref:`TextureRect`, and does not work properly if used inside of other ``AtlasTexture`` resources. Multiple ``AtlasTexture`` resources can be used to crop multiple textures from the atlas. Using a texture atlas helps to optimize video memory costs and render calls compared to using multiple small files. + +**Note:** AtlasTextures don't support repetition. The :ref:`Texture.FLAG_REPEAT` and :ref:`Texture.FLAG_MIRRORED_REPEAT` flags are ignored when using an AtlasTexture. Properties ---------- diff --git a/classes/class_audioeffect.rst b/classes/class_audioeffect.rst index fd24b78f7..a03e03726 100644 --- a/classes/class_audioeffect.rst +++ b/classes/class_audioeffect.rst @@ -11,7 +11,7 @@ AudioEffect **Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` -**Inherited By:** :ref:`AudioEffectAmplify`, :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:`AudioEffectLimiter`, :ref:`AudioEffectPanner`, :ref:`AudioEffectPhaser`, :ref:`AudioEffectPitchShift`, :ref:`AudioEffectRecord`, :ref:`AudioEffectReverb`, :ref:`AudioEffectSpectrumAnalyzer`, :ref:`AudioEffectStereoEnhance` Audio effect for audio. @@ -20,6 +20,11 @@ Description Base resource for audio bus. Applies an audio effect on the bus that the resource is applied on. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/527 `_ + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_audioeffectcapture.rst b/classes/class_audioeffectcapture.rst new file mode 100644 index 000000000..5680857a9 --- /dev/null +++ b/classes/class_audioeffectcapture.rst @@ -0,0 +1,127 @@ +:github_url: hide + +.. Generated automatically by doc/tools/makerst.py in Godot's source tree. +.. DO NOT EDIT THIS FILE, but the AudioEffectCapture.xml source instead. +.. The source is found in doc/classes or modules//doc_classes. + +.. _class_AudioEffectCapture: + +AudioEffectCapture +================== + +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` + +Captures audio from an audio bus in real-time. + +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 a microphone, implement application defined effects, or to transmit audio over the network. + +Properties +---------- + ++---------------------------+-----------------------------------------------------------------------+---------+ +| :ref:`float` | :ref:`buffer_length` | ``0.1`` | ++---------------------------+-----------------------------------------------------------------------+---------+ + +Methods +------- + ++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`can_get_buffer` **(** :ref:`int` frames **)** |const| | ++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`clear_buffer` **(** **)** | ++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PoolVector2Array` | :ref:`get_buffer` **(** :ref:`int` frames **)** | ++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_buffer_length_frames` **(** **)** |const| | ++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_discarded_frames` **(** **)** |const| | ++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_frames_available` **(** **)** |const| | ++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_pushed_frames` **(** **)** |const| | ++-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+ + +Property Descriptions +--------------------- + +.. _class_AudioEffectCapture_property_buffer_length: + +- :ref:`float` **buffer_length** + ++-----------+--------------------------+ +| *Default* | ``0.1`` | ++-----------+--------------------------+ +| *Setter* | set_buffer_length(value) | ++-----------+--------------------------+ +| *Getter* | get_buffer_length() | ++-----------+--------------------------+ + +Length of the internal ring buffer, in seconds. Setting the buffer length will have no effect if already initialized. + +Method Descriptions +------------------- + +.. _class_AudioEffectCapture_method_can_get_buffer: + +- :ref:`bool` **can_get_buffer** **(** :ref:`int` frames **)** |const| + +Returns ``true`` if at least ``frames`` audio frames are available to read in the internal ring buffer. + +---- + +.. _class_AudioEffectCapture_method_clear_buffer: + +- void **clear_buffer** **(** **)** + +Clears the internal ring buffer. + +---- + +.. _class_AudioEffectCapture_method_get_buffer: + +- :ref:`PoolVector2Array` **get_buffer** **(** :ref:`int` frames **)** + +Gets the next ``frames`` audio samples from the internal ring buffer. + +Returns a :ref:`PoolVector2Array` containing exactly ``frames`` audio samples if available, or an empty :ref:`PoolVector2Array` if insufficient data was available. + +---- + +.. _class_AudioEffectCapture_method_get_buffer_length_frames: + +- :ref:`int` **get_buffer_length_frames** **(** **)** |const| + +Returns the total size of the internal ring buffer in frames. + +---- + +.. _class_AudioEffectCapture_method_get_discarded_frames: + +- :ref:`int` **get_discarded_frames** **(** **)** |const| + +Returns the number of audio frames discarded from the audio bus due to full buffer. + +---- + +.. _class_AudioEffectCapture_method_get_frames_available: + +- :ref:`int` **get_frames_available** **(** **)** |const| + +Returns the number of frames available to read using :ref:`get_buffer`. + +---- + +.. _class_AudioEffectCapture_method_get_pushed_frames: + +- :ref:`int` **get_pushed_frames** **(** **)** |const| + +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.)` +.. |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.)` diff --git a/classes/class_audioeffecthighshelffilter.rst b/classes/class_audioeffecthighshelffilter.rst index 093f89fae..90158451f 100644 --- a/classes/class_audioeffecthighshelffilter.rst +++ b/classes/class_audioeffecthighshelffilter.rst @@ -11,7 +11,12 @@ AudioEffectHighShelfFilter **Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +Reduces all frequencies above the :ref:`AudioEffectFilter.cutoff_hz`. +Tutorials +--------- + +- :doc:`../tutorials/audio/audio_buses` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_audioeffectlowshelffilter.rst b/classes/class_audioeffectlowshelffilter.rst index b798f0dfa..6bb5f49db 100644 --- a/classes/class_audioeffectlowshelffilter.rst +++ b/classes/class_audioeffectlowshelffilter.rst @@ -11,7 +11,12 @@ AudioEffectLowShelfFilter **Inherits:** :ref:`AudioEffectFilter` **<** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` +Reduces all frequencies below the :ref:`AudioEffectFilter.cutoff_hz`. +Tutorials +--------- + +- :doc:`../tutorials/audio/audio_buses` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_audioeffectrecord.rst b/classes/class_audioeffectrecord.rst index 3d93f27b8..7db192fbe 100644 --- a/classes/class_audioeffectrecord.rst +++ b/classes/class_audioeffectrecord.rst @@ -23,6 +23,8 @@ Tutorials - :doc:`../tutorials/audio/recording_with_microphone` +- `https://godotengine.org/asset-library/asset/527 `_ + Properties ---------- diff --git a/classes/class_audioeffectreverb.rst b/classes/class_audioeffectreverb.rst index 824052c64..f65e0b69f 100644 --- a/classes/class_audioeffectreverb.rst +++ b/classes/class_audioeffectreverb.rst @@ -20,6 +20,11 @@ Description Simulates rooms of different sizes. Its parameters can be adjusted to simulate the sound of a specific room. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_audioserver.rst b/classes/class_audioserver.rst index 7ae33334b..f5ce2ff29 100644 --- a/classes/class_audioserver.rst +++ b/classes/class_audioserver.rst @@ -23,6 +23,12 @@ Tutorials - :doc:`../tutorials/audio/audio_buses` +- `https://godotengine.org/asset-library/asset/525 `_ + +- `https://godotengine.org/asset-library/asset/527 `_ + +- `https://godotengine.org/asset-library/asset/528 `_ + Properties ---------- diff --git a/classes/class_audiostream.rst b/classes/class_audiostream.rst index 6799dad5d..207cdb6d5 100644 --- a/classes/class_audiostream.rst +++ b/classes/class_audiostream.rst @@ -11,7 +11,7 @@ AudioStream **Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` -**Inherited By:** :ref:`AudioStreamGenerator`, :ref:`AudioStreamMicrophone`, :ref:`AudioStreamOGGVorbis`, :ref:`AudioStreamRandomPitch`, :ref:`AudioStreamSample` +**Inherited By:** :ref:`AudioStreamGenerator`, :ref:`AudioStreamMP3`, :ref:`AudioStreamMicrophone`, :ref:`AudioStreamOGGVorbis`, :ref:`AudioStreamRandomPitch`, :ref:`AudioStreamSample` Base class for audio streams. @@ -25,6 +25,12 @@ Tutorials - :doc:`../tutorials/audio/audio_streams` +- `https://godotengine.org/asset-library/asset/526 `_ + +- `https://godotengine.org/asset-library/asset/527 `_ + +- `https://godotengine.org/asset-library/asset/528 `_ + Methods ------- diff --git a/classes/class_audiostreamgenerator.rst b/classes/class_audiostreamgenerator.rst index d357a01f8..34d55b324 100644 --- a/classes/class_audiostreamgenerator.rst +++ b/classes/class_audiostreamgenerator.rst @@ -16,7 +16,7 @@ AudioStreamGenerator Tutorials --------- -- `https://github.com/godotengine/godot-demo-projects/tree/master/audio/generator `_ +- `https://godotengine.org/asset-library/asset/526 `_ Properties ---------- diff --git a/classes/class_audiostreammp3.rst b/classes/class_audiostreammp3.rst new file mode 100644 index 000000000..df5990bff --- /dev/null +++ b/classes/class_audiostreammp3.rst @@ -0,0 +1,83 @@ +:github_url: hide + +.. Generated automatically by doc/tools/makerst.py in Godot's source tree. +.. DO NOT EDIT THIS FILE, but the AudioStreamMP3.xml source instead. +.. The source is found in doc/classes or modules//doc_classes. + +.. _class_AudioStreamMP3: + +AudioStreamMP3 +============== + +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` + +MP3 audio stream driver. + +Description +----------- + +MP3 audio stream driver. + +Properties +---------- + ++-------------------------------------------+---------------------------------------------------------------+-----------------------+ +| :ref:`PoolByteArray` | :ref:`data` | ``PoolByteArray( )`` | ++-------------------------------------------+---------------------------------------------------------------+-----------------------+ +| :ref:`bool` | :ref:`loop` | ``false`` | ++-------------------------------------------+---------------------------------------------------------------+-----------------------+ +| :ref:`float` | :ref:`loop_offset` | ``0.0`` | ++-------------------------------------------+---------------------------------------------------------------+-----------------------+ + +Property Descriptions +--------------------- + +.. _class_AudioStreamMP3_property_data: + +- :ref:`PoolByteArray` **data** + ++-----------+-----------------------+ +| *Default* | ``PoolByteArray( )`` | ++-----------+-----------------------+ +| *Setter* | set_data(value) | ++-----------+-----------------------+ +| *Getter* | get_data() | ++-----------+-----------------------+ + +Contains the audio data in bytes. + +---- + +.. _class_AudioStreamMP3_property_loop: + +- :ref:`bool` **loop** + ++-----------+-----------------+ +| *Default* | ``false`` | ++-----------+-----------------+ +| *Setter* | set_loop(value) | ++-----------+-----------------+ +| *Getter* | has_loop() | ++-----------+-----------------+ + +If ``true``, the stream will automatically loop when it reaches the end. + +---- + +.. _class_AudioStreamMP3_property_loop_offset: + +- :ref:`float` **loop_offset** + ++-----------+------------------------+ +| *Default* | ``0.0`` | ++-----------+------------------------+ +| *Setter* | set_loop_offset(value) | ++-----------+------------------------+ +| *Getter* | get_loop_offset() | ++-----------+------------------------+ + +Time in seconds at which the stream starts after being looped. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_audiostreamplayback.rst b/classes/class_audiostreamplayback.rst index 1a76f4d2b..17581a9a6 100644 --- a/classes/class_audiostreamplayback.rst +++ b/classes/class_audiostreamplayback.rst @@ -20,6 +20,11 @@ Description Can play, loop, pause a scroll through audio. See :ref:`AudioStream` and :ref:`AudioStreamOGGVorbis` for usage. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/526 `_ + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_audiostreamplayer.rst b/classes/class_audiostreamplayer.rst index ca8e65cde..6c3769536 100644 --- a/classes/class_audiostreamplayer.rst +++ b/classes/class_audiostreamplayer.rst @@ -23,6 +23,16 @@ Tutorials - :doc:`../tutorials/audio/audio_streams` +- `https://godotengine.org/asset-library/asset/515 `_ + +- `https://godotengine.org/asset-library/asset/525 `_ + +- `https://godotengine.org/asset-library/asset/526 `_ + +- `https://godotengine.org/asset-library/asset/527 `_ + +- `https://godotengine.org/asset-library/asset/528 `_ + Properties ---------- diff --git a/classes/class_audiostreamplayer3d.rst b/classes/class_audiostreamplayer3d.rst index 984a1b3c3..d35de4ace 100644 --- a/classes/class_audiostreamplayer3d.rst +++ b/classes/class_audiostreamplayer3d.rst @@ -16,7 +16,7 @@ Plays 3D sound in 3D space. Description ----------- -Plays a sound effect with directed sound effects, dampens with distance if needed, generates effect of hearable position in space. +Plays a sound effect with directed sound effects, dampens with distance if needed, generates effect of hearable position in space. For greater realism, a low-pass filter is automatically 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 a :ref:`Listener` node to the scene and enabling it by calling :ref:`Listener.make_current` on it. @@ -113,7 +113,7 @@ enum **AttenuationModel**: - **ATTENUATION_LOGARITHMIC** = **2** --- Logarithmic dampening of loudness according to distance. -- **ATTENUATION_DISABLED** = **3** --- No dampening of loudness according to distance. +- **ATTENUATION_DISABLED** = **3** --- No dampening of loudness according to distance. The sound will still be heard positionally, unlike an :ref:`AudioStreamPlayer`. ---- @@ -125,9 +125,9 @@ enum **AttenuationModel**: enum **OutOfRangeMode**: -- **OUT_OF_RANGE_MIX** = **0** --- Mix this audio in, even when it's out of range. +- **OUT_OF_RANGE_MIX** = **0** --- Mix this audio in, even when it's out of range. This increases CPU usage, but keeps the sound playing at the correct position if the camera leaves and enters the ``AudioStreamPlayer3D``'s :ref:`max_distance` radius. -- **OUT_OF_RANGE_PAUSE** = **1** --- Pause this audio when it gets out of range. +- **OUT_OF_RANGE_PAUSE** = **1** --- Pause this audio when it gets out of range. This decreases CPU usage, but will cause the sound to restart if the camera leaves and enters the ``AudioStreamPlayer3D``'s :ref:`max_distance` radius. ---- @@ -178,7 +178,7 @@ Areas in which this sound plays. | *Getter* | get_attenuation_filter_cutoff_hz() | +-----------+-----------------------------------------+ -Dampens audio above this frequency, in Hz. +Dampens audio using a low-pass filter above this frequency, in Hz. To disable the dampening effect entirely, set this to ``20500`` as this frequency is above the human hearing limit. ---- @@ -194,7 +194,7 @@ Dampens audio above this frequency, in Hz. | *Getter* | get_attenuation_filter_db() | +-----------+----------------------------------+ -Amount how much the filter affects the loudness, in dB. +Amount how much the filter affects the loudness, in decibels. ---- @@ -226,7 +226,7 @@ Decides if audio should get quieter with distance linearly, quadratically, logar | *Getter* | is_autoplay_enabled() | +-----------+-----------------------+ -If ``true``, audio plays when added to scene tree. +If ``true``, audio plays when the AudioStreamPlayer3D node is added to scene tree. ---- @@ -242,7 +242,7 @@ If ``true``, audio plays when added to scene tree. | *Getter* | get_bus() | +-----------+----------------+ -Bus on which this audio is playing. +The bus on which this audio is playing. ---- @@ -306,7 +306,7 @@ If ``true``, the audio should be dampened according to the direction of the soun | *Getter* | get_emission_angle_filter_attenuation_db() | +-----------+-------------------------------------------------+ -Dampens audio if camera is outside of :ref:`emission_angle_degrees` and :ref:`emission_angle_enabled` is set by this factor, in dB. +Dampens audio if camera is outside of :ref:`emission_angle_degrees` and :ref:`emission_angle_enabled` is set by this factor, in decibels. ---- @@ -322,7 +322,7 @@ Dampens audio if camera is outside of :ref:`emission_angle_degrees` object to be played. +The :ref:`AudioStream` resource to be played. ---- @@ -414,7 +414,7 @@ The :ref:`AudioStream` object to be played. | *Getter* | get_stream_paused() | +-----------+--------------------------+ -If ``true``, the playback is paused. You can resume it by setting ``stream_paused`` to ``false``. +If ``true``, the playback is paused. You can resume it by setting :ref:`stream_paused` to ``false``. ---- @@ -430,7 +430,7 @@ If ``true``, the playback is paused. You can resume it by setting ``stream_pause | *Getter* | get_unit_db() | +-----------+--------------------+ -Base sound level unaffected by dampening, in dB. +The base sound level unaffected by dampening, in decibels. ---- @@ -446,7 +446,7 @@ Base sound level unaffected by dampening, in dB. | *Getter* | get_unit_size() | +-----------+----------------------+ -Factor for the attenuation effect. +The factor for the attenuation effect. Higher values make the sound audible over a larger distance. Method Descriptions ------------------- diff --git a/classes/class_backbuffercopy.rst b/classes/class_backbuffercopy.rst index aadbb7d88..78dbf01a1 100644 --- a/classes/class_backbuffercopy.rst +++ b/classes/class_backbuffercopy.rst @@ -16,7 +16,7 @@ Copies a region of the screen (or the whole screen) to a buffer so it can be acc Description ----------- -Node for back-buffering the currently-displayed screen. The region defined in the BackBufferCopy node is bufferized with the content of the screen it covers, or the entire screen according to the copy mode set. Use the ``texture(SCREEN_TEXTURE, ...)`` function in your shader scripts to access the buffer. +Node for back-buffering the currently-displayed screen. The region defined in the BackBufferCopy node is buffered with the content of the screen it covers, or the entire screen according to the copy mode set. Use the ``texture(SCREEN_TEXTURE, ...)`` function in your shader scripts to access the buffer. **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. diff --git a/classes/class_bakedlightmap.rst b/classes/class_bakedlightmap.rst index ae2c04bc5..984f79d6c 100644 --- a/classes/class_bakedlightmap.rst +++ b/classes/class_bakedlightmap.rst @@ -18,8 +18,6 @@ Description Baked lightmaps are an alternative workflow for adding indirect (or baked) lighting to a scene. Unlike the :ref:`GIProbe` approach, baked lightmaps work fine on low-end PCs and mobile devices as they consume almost no resources in run-time. -**Note:** This node has many known bugs and will be `rewritten for Godot 4.0 `_. See `GitHub issue #30929 `_. - Tutorials --------- @@ -28,38 +26,58 @@ Tutorials Properties ---------- -+----------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------------+ -| :ref:`float` | :ref:`bake_cell_size` | ``0.25`` | -+----------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------------+ -| :ref:`float` | :ref:`bake_default_texels_per_unit` | ``20.0`` | -+----------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------------+ -| :ref:`float` | :ref:`bake_energy` | ``1.0`` | -+----------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------------+ -| :ref:`Vector3` | :ref:`bake_extents` | ``Vector3( 10, 10, 10 )`` | -+----------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------------+ -| :ref:`bool` | :ref:`bake_hdr` | ``false`` | -+----------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------------+ -| :ref:`BakeMode` | :ref:`bake_mode` | ``0`` | -+----------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------------+ -| :ref:`float` | :ref:`bake_propagation` | ``1.0`` | -+----------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------------+ -| :ref:`BakeQuality` | :ref:`bake_quality` | ``1`` | -+----------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------------+ -| :ref:`float` | :ref:`capture_cell_size` | ``0.5`` | -+----------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------------+ -| :ref:`String` | :ref:`image_path` | ``"."`` | -+----------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------------+ -| :ref:`BakedLightmapData` | :ref:`light_data` | | -+----------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------------+ ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`bool` | :ref:`atlas_generate` | ``true`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`int` | :ref:`atlas_max_size` | ``4096`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`float` | :ref:`bias` | ``0.005`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`int` | :ref:`bounces` | ``3`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`float` | :ref:`capture_cell_size` | ``0.5`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`bool` | :ref:`capture_enabled` | ``true`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`float` | :ref:`capture_propagation` | ``1.0`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`BakeQuality` | :ref:`capture_quality` | ``1`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`float` | :ref:`default_texels_per_unit` | ``16.0`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`Color` | :ref:`environment_custom_color` | | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`float` | :ref:`environment_custom_energy` | | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`Sky` | :ref:`environment_custom_sky` | | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`Vector3` | :ref:`environment_custom_sky_rotation_degrees` | | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`Color` | :ref:`environment_min_light` | ``Color( 0, 0, 0, 1 )`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`EnvironmentMode` | :ref:`environment_mode` | ``0`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`Vector3` | :ref:`extents` | ``Vector3( 10, 10, 10 )`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`String` | :ref:`image_path` | | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`BakedLightmapData` | :ref:`light_data` | | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`BakeQuality` | :ref:`quality` | ``1`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`bool` | :ref:`use_color` | ``true`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`bool` | :ref:`use_denoiser` | ``true`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ +| :ref:`bool` | :ref:`use_hdr` | ``true`` | ++------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------------------+ Methods ------- -+------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`BakeError` | :ref:`bake` **(** :ref:`Node` from_node=null, :ref:`bool` create_visual_debug=false **)** | -+------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`debug_bake` **(** **)** | -+------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ ++------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`BakeError` | :ref:`bake` **(** :ref:`Node` from_node=null, :ref:`String` data_save_path="" **)** | ++------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+ Enumerations ------------ @@ -72,27 +90,17 @@ Enumerations .. _class_BakedLightmap_constant_BAKE_QUALITY_HIGH: +.. _class_BakedLightmap_constant_BAKE_QUALITY_ULTRA: + enum **BakeQuality**: - **BAKE_QUALITY_LOW** = **0** --- The lowest bake quality mode. Fastest to calculate. - **BAKE_QUALITY_MEDIUM** = **1** --- The default bake quality mode. -- **BAKE_QUALITY_HIGH** = **2** --- The highest bake quality mode. Takes longer to calculate. +- **BAKE_QUALITY_HIGH** = **2** --- A higher bake quality mode. Takes longer to calculate. ----- - -.. _enum_BakedLightmap_BakeMode: - -.. _class_BakedLightmap_constant_BAKE_MODE_CONE_TRACE: - -.. _class_BakedLightmap_constant_BAKE_MODE_RAY_TRACE: - -enum **BakeMode**: - -- **BAKE_MODE_CONE_TRACE** = **0** --- Less precise but faster bake mode. - -- **BAKE_MODE_RAY_TRACE** = **1** --- More precise bake mode but can take considerably longer to bake. +- **BAKE_QUALITY_ULTRA** = **3** --- The highest bake quality mode. Takes the longest to calculate. ---- @@ -106,8 +114,14 @@ enum **BakeMode**: .. _class_BakedLightmap_constant_BAKE_ERROR_CANT_CREATE_IMAGE: +.. _class_BakedLightmap_constant_BAKE_ERROR_LIGHTMAP_SIZE: + +.. _class_BakedLightmap_constant_BAKE_ERROR_INVALID_MESH: + .. _class_BakedLightmap_constant_BAKE_ERROR_USER_ABORTED: +.. _class_BakedLightmap_constant_BAKE_ERROR_NO_LIGHTMAPPER: + enum **BakeError**: - **BAKE_ERROR_OK** = **0** --- Baking was successful. @@ -118,136 +132,100 @@ enum **BakeError**: - **BAKE_ERROR_CANT_CREATE_IMAGE** = **3** --- Returns when the baker cannot save per-mesh textures to file. -- **BAKE_ERROR_USER_ABORTED** = **4** --- Returns if user cancels baking. +- **BAKE_ERROR_LIGHTMAP_SIZE** = **4** --- The size of the generated lightmaps is too large. + +- **BAKE_ERROR_INVALID_MESH** = **5** --- Some mesh contains UV2 values outside the ``[0,1]`` range. + +- **BAKE_ERROR_USER_ABORTED** = **6** --- Returns if user cancels baking. + +- **BAKE_ERROR_NO_LIGHTMAPPER** = **7** + +---- + +.. _enum_BakedLightmap_EnvironmentMode: + +.. _class_BakedLightmap_constant_ENVIRONMENT_MODE_DISABLED: + +.. _class_BakedLightmap_constant_ENVIRONMENT_MODE_SCENE: + +.. _class_BakedLightmap_constant_ENVIRONMENT_MODE_CUSTOM_SKY: + +.. _class_BakedLightmap_constant_ENVIRONMENT_MODE_CUSTOM_COLOR: + +enum **EnvironmentMode**: + +- **ENVIRONMENT_MODE_DISABLED** = **0** --- No environment is used during baking. + +- **ENVIRONMENT_MODE_SCENE** = **1** --- The baked environment is automatically picked from the current scene. + +- **ENVIRONMENT_MODE_CUSTOM_SKY** = **2** --- A custom sky is used as environment during baking. + +- **ENVIRONMENT_MODE_CUSTOM_COLOR** = **3** --- A custom solid color is used as environment during baking. Property Descriptions --------------------- -.. _class_BakedLightmap_property_bake_cell_size: +.. _class_BakedLightmap_property_atlas_generate: -- :ref:`float` **bake_cell_size** +- :ref:`bool` **atlas_generate** -+-----------+---------------------------+ -| *Default* | ``0.25`` | -+-----------+---------------------------+ -| *Setter* | set_bake_cell_size(value) | -+-----------+---------------------------+ -| *Getter* | get_bake_cell_size() | -+-----------+---------------------------+ ++-----------+-----------------------------+ +| *Default* | ``true`` | ++-----------+-----------------------------+ +| *Setter* | set_generate_atlas(value) | ++-----------+-----------------------------+ +| *Getter* | is_generate_atlas_enabled() | ++-----------+-----------------------------+ -Grid subdivision size for lightmapper calculation. The default value will work for most cases. Increase for better lighting on small details or if your scene is very large. +When enabled, the lightmapper will merge the textures for all meshes into a single large layered texture. Not supported in GLES2. ---- -.. _class_BakedLightmap_property_bake_default_texels_per_unit: +.. _class_BakedLightmap_property_atlas_max_size: -- :ref:`float` **bake_default_texels_per_unit** - -+-----------+-----------------------------------------+ -| *Default* | ``20.0`` | -+-----------+-----------------------------------------+ -| *Setter* | set_bake_default_texels_per_unit(value) | -+-----------+-----------------------------------------+ -| *Getter* | get_bake_default_texels_per_unit() | -+-----------+-----------------------------------------+ - -If a :ref:`Mesh.lightmap_size_hint` isn't specified, the lightmap baker will dynamically set the lightmap size using this value. This value is measured in texels per world unit. The maximum lightmap texture size is 4096x4096. - ----- - -.. _class_BakedLightmap_property_bake_energy: - -- :ref:`float` **bake_energy** - -+-----------+-------------------+ -| *Default* | ``1.0`` | -+-----------+-------------------+ -| *Setter* | set_energy(value) | -+-----------+-------------------+ -| *Getter* | get_energy() | -+-----------+-------------------+ - -Multiplies the light sources' intensity by this value. For instance, if the value is set to 2, lights will be twice as bright. If the value is set to 0.5, lights will be half as bright. - ----- - -.. _class_BakedLightmap_property_bake_extents: - -- :ref:`Vector3` **bake_extents** +- :ref:`int` **atlas_max_size** +-----------+---------------------------+ -| *Default* | ``Vector3( 10, 10, 10 )`` | +| *Default* | ``4096`` | +-----------+---------------------------+ -| *Setter* | set_extents(value) | +| *Setter* | set_max_atlas_size(value) | +-----------+---------------------------+ -| *Getter* | get_extents() | +| *Getter* | get_max_atlas_size() | +-----------+---------------------------+ -The size of the affected area. +Maximum size of each lightmap layer, only used when :ref:`atlas_generate` is enabled. ---- -.. _class_BakedLightmap_property_bake_hdr: +.. _class_BakedLightmap_property_bias: -- :ref:`bool` **bake_hdr** +- :ref:`float` **bias** -+-----------+----------------+ -| *Default* | ``false`` | -+-----------+----------------+ -| *Setter* | set_hdr(value) | -+-----------+----------------+ -| *Getter* | is_hdr() | -+-----------+----------------+ ++-----------+-----------------+ +| *Default* | ``0.005`` | ++-----------+-----------------+ +| *Setter* | set_bias(value) | ++-----------+-----------------+ +| *Getter* | get_bias() | ++-----------+-----------------+ -If ``true``, the lightmap can capture light values greater than ``1.0``. Turning this off will result in a smaller file size. +Raycasting bias used during baking to avoid floating point precission issues. ---- -.. _class_BakedLightmap_property_bake_mode: +.. _class_BakedLightmap_property_bounces: -- :ref:`BakeMode` **bake_mode** +- :ref:`int` **bounces** -+-----------+----------------------+ -| *Default* | ``0`` | -+-----------+----------------------+ -| *Setter* | set_bake_mode(value) | -+-----------+----------------------+ -| *Getter* | get_bake_mode() | -+-----------+----------------------+ ++-----------+--------------------+ +| *Default* | ``3`` | ++-----------+--------------------+ +| *Setter* | set_bounces(value) | ++-----------+--------------------+ +| *Getter* | get_bounces() | ++-----------+--------------------+ -Lightmapping mode. See :ref:`BakeMode`. - ----- - -.. _class_BakedLightmap_property_bake_propagation: - -- :ref:`float` **bake_propagation** - -+-----------+------------------------+ -| *Default* | ``1.0`` | -+-----------+------------------------+ -| *Setter* | set_propagation(value) | -+-----------+------------------------+ -| *Getter* | get_propagation() | -+-----------+------------------------+ - -Defines how far the light will travel before it is no longer effective. The higher the number, the farther the light will travel. For instance, if the value is set to 2, the light will go twice as far. If the value is set to 0.5, the light will only go half as far. - ----- - -.. _class_BakedLightmap_property_bake_quality: - -- :ref:`BakeQuality` **bake_quality** - -+-----------+-------------------------+ -| *Default* | ``1`` | -+-----------+-------------------------+ -| *Setter* | set_bake_quality(value) | -+-----------+-------------------------+ -| *Getter* | get_bake_quality() | -+-----------+-------------------------+ - -Three quality modes are available. Higher quality requires more rendering time. See :ref:`BakeQuality`. +Number of light bounces that are taken into account during baking. ---- @@ -263,7 +241,175 @@ Three quality modes are available. Higher quality requires more rendering time. | *Getter* | get_capture_cell_size() | +-----------+------------------------------+ -Grid size used for real-time capture information on dynamic objects. Cannot be larger than :ref:`bake_cell_size`. +Grid size used for real-time capture information on dynamic objects. + +---- + +.. _class_BakedLightmap_property_capture_enabled: + +- :ref:`bool` **capture_enabled** + ++-----------+----------------------------+ +| *Default* | ``true`` | ++-----------+----------------------------+ +| *Setter* | set_capture_enabled(value) | ++-----------+----------------------------+ +| *Getter* | get_capture_enabled() | ++-----------+----------------------------+ + +When enabled, an octree containing the scene's lighting information will be computed. This octree will then be used to light dynamic objects in the scene. + +---- + +.. _class_BakedLightmap_property_capture_propagation: + +- :ref:`float` **capture_propagation** + ++-----------+--------------------------------+ +| *Default* | ``1.0`` | ++-----------+--------------------------------+ +| *Setter* | set_capture_propagation(value) | ++-----------+--------------------------------+ +| *Getter* | get_capture_propagation() | ++-----------+--------------------------------+ + +Bias value to reduce the amount of light proagation in the captured octree. + +---- + +.. _class_BakedLightmap_property_capture_quality: + +- :ref:`BakeQuality` **capture_quality** + ++-----------+----------------------------+ +| *Default* | ``1`` | ++-----------+----------------------------+ +| *Setter* | set_capture_quality(value) | ++-----------+----------------------------+ +| *Getter* | get_capture_quality() | ++-----------+----------------------------+ + +Bake quality of the capture data. + +---- + +.. _class_BakedLightmap_property_default_texels_per_unit: + +- :ref:`float` **default_texels_per_unit** + ++-----------+------------------------------------+ +| *Default* | ``16.0`` | ++-----------+------------------------------------+ +| *Setter* | set_default_texels_per_unit(value) | ++-----------+------------------------------------+ +| *Getter* | get_default_texels_per_unit() | ++-----------+------------------------------------+ + +If a baked mesh doesn't have a UV2 size hint, this value will be used to roughly compute a suitable lightmap size. + +---- + +.. _class_BakedLightmap_property_environment_custom_color: + +- :ref:`Color` **environment_custom_color** + ++----------+-------------------------------------+ +| *Setter* | set_environment_custom_color(value) | ++----------+-------------------------------------+ +| *Getter* | get_environment_custom_color() | ++----------+-------------------------------------+ + +The environment color when :ref:`environment_mode` is set to :ref:`ENVIRONMENT_MODE_CUSTOM_COLOR`. + +---- + +.. _class_BakedLightmap_property_environment_custom_energy: + +- :ref:`float` **environment_custom_energy** + ++----------+--------------------------------------+ +| *Setter* | set_environment_custom_energy(value) | ++----------+--------------------------------------+ +| *Getter* | get_environment_custom_energy() | ++----------+--------------------------------------+ + +The energy scaling factor when when :ref:`environment_mode` is set to :ref:`ENVIRONMENT_MODE_CUSTOM_COLOR` or :ref:`ENVIRONMENT_MODE_CUSTOM_SKY`. + +---- + +.. _class_BakedLightmap_property_environment_custom_sky: + +- :ref:`Sky` **environment_custom_sky** + ++----------+-----------------------------------+ +| *Setter* | set_environment_custom_sky(value) | ++----------+-----------------------------------+ +| *Getter* | get_environment_custom_sky() | ++----------+-----------------------------------+ + +The :ref:`Sky` resource to use when :ref:`environment_mode` is set o :ref:`ENVIRONMENT_MODE_CUSTOM_SKY`. + +---- + +.. _class_BakedLightmap_property_environment_custom_sky_rotation_degrees: + +- :ref:`Vector3` **environment_custom_sky_rotation_degrees** + ++----------+----------------------------------------------------+ +| *Setter* | set_environment_custom_sky_rotation_degrees(value) | ++----------+----------------------------------------------------+ +| *Getter* | get_environment_custom_sky_rotation_degrees() | ++----------+----------------------------------------------------+ + +The rotation of the baked custom sky. + +---- + +.. _class_BakedLightmap_property_environment_min_light: + +- :ref:`Color` **environment_min_light** + ++-----------+----------------------------------+ +| *Default* | ``Color( 0, 0, 0, 1 )`` | ++-----------+----------------------------------+ +| *Setter* | set_environment_min_light(value) | ++-----------+----------------------------------+ +| *Getter* | get_environment_min_light() | ++-----------+----------------------------------+ + +Minimum ambient light for all the lightmap texels. This doesn't take into account any occlusion from the scene's geometry, it simply ensures a minimum amount of light on all the lightmap texels. Can be used for artistic control on shadow color. + +---- + +.. _class_BakedLightmap_property_environment_mode: + +- :ref:`EnvironmentMode` **environment_mode** + ++-----------+-----------------------------+ +| *Default* | ``0`` | ++-----------+-----------------------------+ +| *Setter* | set_environment_mode(value) | ++-----------+-----------------------------+ +| *Getter* | get_environment_mode() | ++-----------+-----------------------------+ + +Decides which environment to use during baking. + +---- + +.. _class_BakedLightmap_property_extents: + +- :ref:`Vector3` **extents** + ++-----------+---------------------------+ +| *Default* | ``Vector3( 10, 10, 10 )`` | ++-----------+---------------------------+ +| *Setter* | set_extents(value) | ++-----------+---------------------------+ +| *Getter* | get_extents() | ++-----------+---------------------------+ + +Size of the baked lightmap. Only meshes inside this region will be included in the baked lightmap, also used as the bounds of the captured region for dynamic lighting. ---- @@ -271,15 +417,13 @@ Grid size used for real-time capture information on dynamic objects. Cannot be l - :ref:`String` **image_path** -+-----------+-----------------------+ -| *Default* | ``"."`` | -+-----------+-----------------------+ -| *Setter* | set_image_path(value) | -+-----------+-----------------------+ -| *Getter* | get_image_path() | -+-----------+-----------------------+ ++----------+-----------------------+ +| *Setter* | set_image_path(value) | ++----------+-----------------------+ +| *Getter* | get_image_path() | ++----------+-----------------------+ -The location where lightmaps will be saved. +Deprecated, in previous versions it determined the location where lightmaps were be saved. ---- @@ -295,22 +439,80 @@ The location where lightmaps will be saved. The calculated light data. +---- + +.. _class_BakedLightmap_property_quality: + +- :ref:`BakeQuality` **quality** + ++-----------+-------------------------+ +| *Default* | ``1`` | ++-----------+-------------------------+ +| *Setter* | set_bake_quality(value) | ++-----------+-------------------------+ +| *Getter* | get_bake_quality() | ++-----------+-------------------------+ + +Determines the amount of samples per texel used in indrect light baking. The amount of samples for each quality level can be configured in the project settings. + +---- + +.. _class_BakedLightmap_property_use_color: + +- :ref:`bool` **use_color** + ++-----------+----------------------+ +| *Default* | ``true`` | ++-----------+----------------------+ +| *Setter* | set_use_color(value) | ++-----------+----------------------+ +| *Getter* | is_using_color() | ++-----------+----------------------+ + +Store full color values in the lightmap textures. When disabled, lightmap textures will store a single brightness channel. Can be disabled to reduce disk usage if the scene contains only white lights or you don't mind losing color information in indirect lighting. + +---- + +.. _class_BakedLightmap_property_use_denoiser: + +- :ref:`bool` **use_denoiser** + ++-----------+-------------------------+ +| *Default* | ``true`` | ++-----------+-------------------------+ +| *Setter* | set_use_denoiser(value) | ++-----------+-------------------------+ +| *Getter* | is_using_denoiser() | ++-----------+-------------------------+ + +When enabled, a lightmap denoiser will be used to reduce the noise inherent to Monte Carlo based global illumination. + +---- + +.. _class_BakedLightmap_property_use_hdr: + +- :ref:`bool` **use_hdr** + ++-----------+--------------------+ +| *Default* | ``true`` | ++-----------+--------------------+ +| *Setter* | set_use_hdr(value) | ++-----------+--------------------+ +| *Getter* | is_using_hdr() | ++-----------+--------------------+ + +If ``true``, stores the lightmap textures in a high dynamic range format (EXR). If ``false``, stores the lightmap texture in a low dynamic range PNG image. This can be set to ``false`` to reduce disk usage, but light values over 1.0 will be clamped and you may see banding caused by the reduced precision. + +**Note:** Setting :ref:`use_hdr` to ``true`` will decrease lightmap banding even when using the GLES2 backend or if :ref:`ProjectSettings.rendering/quality/depth/hdr` is ``false``. + Method Descriptions ------------------- .. _class_BakedLightmap_method_bake: -- :ref:`BakeError` **bake** **(** :ref:`Node` from_node=null, :ref:`bool` create_visual_debug=false **)** +- :ref:`BakeError` **bake** **(** :ref:`Node` from_node=null, :ref:`String` data_save_path="" **)** -Bakes the lightmaps within the currently edited scene. Returns a :ref:`BakeError` to signify if the bake was successful, or if unsuccessful, how the bake failed. - ----- - -.. _class_BakedLightmap_method_debug_bake: - -- void **debug_bake** **(** **)** - -Executes a dry run bake of lightmaps within the currently edited scene. +Bakes the lightmap, scanning from the given ``from_node`` root and saves the resulting :ref:`BakedLightmapData` in ``data_save_path``. If no save path is provided it will try to match the path from the current :ref:`light_data`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_bakedlightmapdata.rst b/classes/class_bakedlightmapdata.rst index 9dc807885..ee6334b6a 100644 --- a/classes/class_bakedlightmapdata.rst +++ b/classes/class_bakedlightmapdata.rst @@ -25,23 +25,27 @@ Properties +-------------------------------------------+------------------------------------------------------------------------------------+-----------------------------------------------------+ | :ref:`float` | :ref:`energy` | ``1.0`` | +-------------------------------------------+------------------------------------------------------------------------------------+-----------------------------------------------------+ +| :ref:`bool` | :ref:`interior` | ``false`` | ++-------------------------------------------+------------------------------------------------------------------------------------+-----------------------------------------------------+ | :ref:`PoolByteArray` | :ref:`octree` | ``PoolByteArray( )`` | +-------------------------------------------+------------------------------------------------------------------------------------+-----------------------------------------------------+ Methods ------- -+---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_user` **(** :ref:`NodePath` path, :ref:`Texture` lightmap, :ref:`int` instance **)** | -+---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_users` **(** **)** | -+---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_user_count` **(** **)** |const| | -+---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Texture` | :ref:`get_user_lightmap` **(** :ref:`int` user_idx **)** |const| | -+---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`NodePath` | :ref:`get_user_path` **(** :ref:`int` user_idx **)** |const| | -+---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`add_user` **(** :ref:`NodePath` path, :ref:`Resource` lightmap, :ref:`int` lightmap_slice, :ref:`Rect2` lightmap_uv_rect, :ref:`int` instance **)** | ++---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`clear_data` **(** **)** | ++---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`clear_users` **(** **)** | ++---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_user_count` **(** **)** |const| | ++---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Resource` | :ref:`get_user_lightmap` **(** :ref:`int` user_idx **)** |const| | ++---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`NodePath` | :ref:`get_user_path` **(** :ref:`int` user_idx **)** |const| | ++---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Property Descriptions --------------------- @@ -100,6 +104,24 @@ Property Descriptions | *Getter* | get_energy() | +-----------+-------------------+ +Global energy multiplier for baked and dynamic capture objects. + +---- + +.. _class_BakedLightmapData_property_interior: + +- :ref:`bool` **interior** + ++-----------+---------------------+ +| *Default* | ``false`` | ++-----------+---------------------+ +| *Setter* | set_interior(value) | ++-----------+---------------------+ +| *Getter* | is_interior() | ++-----------+---------------------+ + +Controls whether dynamic capture objects receive environment lighting or not. + ---- .. _class_BakedLightmapData_property_octree: @@ -119,7 +141,13 @@ Method Descriptions .. _class_BakedLightmapData_method_add_user: -- void **add_user** **(** :ref:`NodePath` path, :ref:`Texture` lightmap, :ref:`int` instance **)** +- void **add_user** **(** :ref:`NodePath` path, :ref:`Resource` lightmap, :ref:`int` lightmap_slice, :ref:`Rect2` lightmap_uv_rect, :ref:`int` instance **)** + +---- + +.. _class_BakedLightmapData_method_clear_data: + +- void **clear_data** **(** **)** ---- @@ -137,7 +165,7 @@ Method Descriptions .. _class_BakedLightmapData_method_get_user_lightmap: -- :ref:`Texture` **get_user_lightmap** **(** :ref:`int` user_idx **)** |const| +- :ref:`Resource` **get_user_lightmap** **(** :ref:`int` user_idx **)** |const| ---- diff --git a/classes/class_basebutton.rst b/classes/class_basebutton.rst index 9238d4feb..5a7aedf44 100644 --- a/classes/class_basebutton.rst +++ b/classes/class_basebutton.rst @@ -201,7 +201,7 @@ If ``true``, the button is in disabled state and can't be clicked or toggled. | *Getter* | get_enabled_focus_mode() | +-----------+-------------------------------+ -Focus access mode to use when switching between enabled/disabled (see :ref:`Control.focus_mode` and :ref:`disabled`). +*Deprecated.* This property has been deprecated due to redundancy and no longer has any effect when set. Please use :ref:`Control.focus_mode` instead. ---- diff --git a/classes/class_basis.rst b/classes/class_basis.rst index f06c96260..a44143aaf 100644 --- a/classes/class_basis.rst +++ b/classes/class_basis.rst @@ -25,10 +25,20 @@ For more information, read the "Matrices and transforms" documentation article. Tutorials --------- +- :doc:`../tutorials/math/index` + - :doc:`../tutorials/math/matrices_and_transforms` - :doc:`../tutorials/3d/using_transforms` +- `https://godotengine.org/asset-library/asset/584 `_ + +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/676 `_ + +- `https://godotengine.org/asset-library/asset/583 `_ + Properties ---------- @@ -234,6 +244,8 @@ Returns the inverse of the matrix. Returns ``true`` if this basis and ``b`` are approximately equal, by calling ``is_equal_approx`` on each component. +**Note:** For complicated reasons, the epsilon argument is always discarded. Don't use the epsilon argument, it does nothing. + ---- .. _class_Basis_method_orthonormalized: diff --git a/classes/class_bool.rst b/classes/class_bool.rst index 0a5a28db3..a591431f5 100644 --- a/classes/class_bool.rst +++ b/classes/class_bool.rst @@ -14,7 +14,7 @@ Boolean built-in type. Description ----------- -Boolean is a built-in type. There are two boolean values: ``true`` and ``false``. You can think of it as an switch with on or off (1 or 0) setting. Booleans are used in programming for logic in condition statements, like ``if`` statements. +Boolean is a built-in type. There are two boolean values: ``true`` and ``false``. You can think of it as a switch with on or off (1 or 0) setting. Booleans are used in programming for logic in condition statements, like ``if`` statements. Booleans can be directly used in ``if`` statements. The code below demonstrates this on the ``if can_shoot:`` line. You don't need to use ``== true``, you only need ``if can_shoot:``. Similarly, use ``if not can_shoot:`` rather than ``== false``. diff --git a/classes/class_boxshape.rst b/classes/class_boxshape.rst index 0b3d8ab65..0e16b075d 100644 --- a/classes/class_boxshape.rst +++ b/classes/class_boxshape.rst @@ -18,6 +18,15 @@ Description 3D box shape that can be a child of a :ref:`PhysicsBody` or :ref:`Area`. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/675 `_ + +- `https://godotengine.org/asset-library/asset/126 `_ + +- `https://godotengine.org/asset-library/asset/125 `_ + Properties ---------- diff --git a/classes/class_button.rst b/classes/class_button.rst index d2ac56441..c8fee3e96 100644 --- a/classes/class_button.rst +++ b/classes/class_button.rst @@ -35,6 +35,17 @@ Button is the standard themed button. It can contain text and an icon, and will Buttons (like all Control nodes) can also be created in the editor, but some situations may require creating them from code. +See also :ref:`BaseButton` which contains common properties and methods associated with this node. + +**Note:** Buttons do not interpret touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use :ref:`TouchScreenButton` for buttons that trigger gameplay movement or actions, as :ref:`TouchScreenButton` supports multitouch. + +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/515 `_ + +- `https://godotengine.org/asset-library/asset/677 `_ + Properties ---------- diff --git a/classes/class_camera.rst b/classes/class_camera.rst index 31f53f819..064903573 100644 --- a/classes/class_camera.rst +++ b/classes/class_camera.rst @@ -20,6 +20,11 @@ Description Camera is a special node that displays what is visible from its current location. 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. In other words, a camera just provides 3D display capabilities to a :ref:`Viewport`, and, without one, a scene registered in that :ref:`Viewport` (or higher viewports) can't be displayed. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- @@ -234,6 +239,16 @@ The distance to the far culling boundary for this camera relative to its local Z The camera's field of view angle (in degrees). Only applicable in perspective mode. Since :ref:`keep_aspect` locks one axis, ``fov`` sets the other axis' field of view angle. +For reference, the default vertical field of view value (``75.0``) is equivalent to a horizontal FOV of: + +- ~91.31 degrees in a 4:3 viewport + +- ~101.67 degrees in a 16:10 viewport + +- ~107.51 degrees in a 16:9 viewport + +- ~121.63 degrees in a 21:9 viewport + ---- .. _class_Camera_property_frustum_offset: @@ -477,6 +492,15 @@ Sets the camera projection to perspective mode (see :ref:`PROJECTION_PERSPECTIVE Returns the 2D coordinate in the :ref:`Viewport` rectangle that maps to the given 3D point in worldspace. +**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: + +:: + + # This code block is part of a script that inherits from Spatial. + # `control` is a reference to a node inheriting from Control. + control.visible = not get_viewport().get_camera().is_position_behind(global_transform.origin) + control.rect_position = get_viewport().get_camera().unproject_position(global_transform.origin) + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_camera2d.rst b/classes/class_camera2d.rst index d0d8b98d2..2999da9a8 100644 --- a/classes/class_camera2d.rst +++ b/classes/class_camera2d.rst @@ -22,6 +22,15 @@ This node is intended to be a simple helper to get things going quickly and it m 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_camera_screen_center` to get the real position. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/120 `_ + +- `https://godotengine.org/asset-library/asset/112 `_ + +- `https://godotengine.org/asset-library/asset/110 `_ + Properties ---------- diff --git a/classes/class_canvasitem.rst b/classes/class_canvasitem.rst index 92fbb8751..2bcffa409 100644 --- a/classes/class_canvasitem.rst +++ b/classes/class_canvasitem.rst @@ -37,6 +37,8 @@ Tutorials - :doc:`../tutorials/2d/custom_drawing_in_2d` +- `https://godotengine.org/asset-library/asset/528 `_ + Properties ---------- @@ -178,7 +180,7 @@ Emitted when becoming hidden. - **item_rect_changed** **(** **)** -Emitted when the item rect has changed. +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:`Sprite.texture`). ---- @@ -512,7 +514,7 @@ Sets a custom transform for drawing via matrix. Anything drawn afterwards will b - void **draw_string** **(** :ref:`Font` font, :ref:`Vector2` position, :ref:`String` text, :ref:`Color` modulate=Color( 1, 1, 1, 1 ), :ref:`int` clip_w=-1 **)** -Draws ``text`` using the specified ``font`` at the ``position`` (top-left corner). The text will have its color multiplied by ``modulate``. If ``clip_w`` 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 ``position`` (bottom-left corner using the baseline of the font). The text will have its color multiplied by ``modulate``. If ``clip_w`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. **Example using the default project font:** diff --git a/classes/class_canvaslayer.rst b/classes/class_canvaslayer.rst index 1ac293fca..598028a43 100644 --- a/classes/class_canvaslayer.rst +++ b/classes/class_canvaslayer.rst @@ -27,6 +27,8 @@ Tutorials - :doc:`../tutorials/2d/canvas_layers` +- `https://godotengine.org/asset-library/asset/515 `_ + Properties ---------- diff --git a/classes/class_capsuleshape.rst b/classes/class_capsuleshape.rst index 08ad8ae7d..17e98b946 100644 --- a/classes/class_capsuleshape.rst +++ b/classes/class_capsuleshape.rst @@ -18,6 +18,11 @@ Description Capsule shape for collisions. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/675 `_ + Properties ---------- diff --git a/classes/class_checkbox.rst b/classes/class_checkbox.rst index 27ae648bd..7ebe4b234 100644 --- a/classes/class_checkbox.rst +++ b/classes/class_checkbox.rst @@ -16,7 +16,9 @@ Binary choice user interface widget. See also :ref:`CheckButton` in functionality, but it has a different apperance. To follow established UX patterns, it's recommended to use CheckBox when toggling it has **no** immediate effect on something. For instance, it should be used when toggling it will only do something once a confirmation button is pressed. +A checkbox allows the user to make a binary choice (choosing only one of two possible options). It's similar to :ref:`CheckButton` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use CheckBox when toggling it has **no** immediate effect on something. For instance, it should be used when toggling it will only do something once a confirmation button is pressed. + +See also :ref:`BaseButton` which contains common properties and methods associated with this node. Properties ---------- diff --git a/classes/class_checkbutton.rst b/classes/class_checkbutton.rst index 7a4836d10..76fb93069 100644 --- a/classes/class_checkbutton.rst +++ b/classes/class_checkbutton.rst @@ -16,7 +16,9 @@ Checkable button. See also :ref:`CheckBox`. Description ----------- -CheckButton is a toggle button displayed as a check field. It's similar to :ref:`CheckBox` in functionality, but it has a different apperance. To follow established UX patterns, it's recommended to use CheckButton when toggling it has an **immediate** effect on something. For instance, it should be used if toggling it enables/disables a setting without requiring the user to press a confirmation button. +CheckButton is a toggle button displayed as a check field. It's similar to :ref:`CheckBox` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use CheckButton when toggling it has an **immediate** effect on something. For instance, it should be used if toggling it enables/disables a setting without requiring the user to press a confirmation button. + +See also :ref:`BaseButton` which contains common properties and methods associated with this node. Properties ---------- diff --git a/classes/class_classdb.rst b/classes/class_classdb.rst index 06007fad3..1265dbead 100644 --- a/classes/class_classdb.rst +++ b/classes/class_classdb.rst @@ -112,6 +112,8 @@ Returns an array with the names all the integer constants of ``class`` or its an 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)``. +**Note:** In exported release builds the debug info is not available, so the returned dictionaries will contain only method names. + ---- .. _class_ClassDB_method_class_get_property: diff --git a/classes/class_clippedcamera.rst b/classes/class_clippedcamera.rst index a308a751b..07fefdab4 100644 --- a/classes/class_clippedcamera.rst +++ b/classes/class_clippedcamera.rst @@ -116,7 +116,7 @@ If ``true``, the camera stops on contact with :ref:`PhysicsBody`_ in the documentation for more information. +The camera's collision mask. Only objects in at least one collision layer matching the mask will be detected. See `Collision layers and masks `_ in the documentation for more information. ---- diff --git a/classes/class_collisionpolygon.rst b/classes/class_collisionpolygon.rst index 51178d2ce..f99e8f323 100644 --- a/classes/class_collisionpolygon.rst +++ b/classes/class_collisionpolygon.rst @@ -26,6 +26,8 @@ Properties +-------------------------------------------------+-----------------------------------------------------------+--------------------------+ | :ref:`bool` | :ref:`disabled` | ``false`` | +-------------------------------------------------+-----------------------------------------------------------+--------------------------+ +| :ref:`float` | :ref:`margin` | ``0.04`` | ++-------------------------------------------------+-----------------------------------------------------------+--------------------------+ | :ref:`PoolVector2Array` | :ref:`polygon` | ``PoolVector2Array( )`` | +-------------------------------------------------+-----------------------------------------------------------+--------------------------+ @@ -64,6 +66,22 @@ If ``true``, no collision will be produced. ---- +.. _class_CollisionPolygon_property_margin: + +- :ref:`float` **margin** + ++-----------+-------------------+ +| *Default* | ``0.04`` | ++-----------+-------------------+ +| *Setter* | set_margin(value) | ++-----------+-------------------+ +| *Getter* | get_margin() | ++-----------+-------------------+ + +The collision margin for the generated :ref:`Shape`. See :ref:`Shape.margin` for more details. + +---- + .. _class_CollisionPolygon_property_polygon: - :ref:`PoolVector2Array` **polygon** diff --git a/classes/class_collisionshape.rst b/classes/class_collisionshape.rst index 3f33e2ec0..d551dc1d2 100644 --- a/classes/class_collisionshape.rst +++ b/classes/class_collisionshape.rst @@ -23,6 +23,12 @@ Tutorials - :doc:`../tutorials/physics/physics_introduction` +- `https://godotengine.org/asset-library/asset/126 `_ + +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_collisionshape2d.rst b/classes/class_collisionshape2d.rst index e0d5f2839..625b97e77 100644 --- a/classes/class_collisionshape2d.rst +++ b/classes/class_collisionshape2d.rst @@ -23,6 +23,12 @@ Tutorials - :doc:`../tutorials/physics/physics_introduction` +- `https://godotengine.org/asset-library/asset/515 `_ + +- `https://godotengine.org/asset-library/asset/121 `_ + +- `https://godotengine.org/asset-library/asset/113 `_ + Properties ---------- diff --git a/classes/class_color.rst b/classes/class_color.rst index 9105e4b33..1862a23ca 100644 --- a/classes/class_color.rst +++ b/classes/class_color.rst @@ -22,6 +22,17 @@ If you want to supply values in a range of 0 to 255, you should use :ref:`@GDScr **Note:** In a boolean context, a Color will evaluate to ``false`` if it's equal to ``Color(0, 0, 0, 1)`` (opaque black). Otherwise, a Color will always evaluate to ``true``. +`Color constants cheatsheet `_ + +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/517 `_ + +- `https://godotengine.org/asset-library/asset/146 `_ + +- `https://godotengine.org/asset-library/asset/133 `_ + Properties ---------- @@ -835,31 +846,31 @@ Constructs a color from an HTML hexadecimal color string in ARGB or RGB format. - :ref:`Color` **Color** **(** :ref:`int` from **)** -Constructs a color from a 32-bit integer (each byte represents a component of the RGBA profile). +Constructs a color from a 32-bit integer in RGBA format (each byte represents a color channel). :: - var c = Color(274) # Equivalent to RGBA(0, 0, 1, 18) + var c = Color(274) # Similar to Color(0.0, 0.0, 0.004, 0.07) ---- - :ref:`Color` **Color** **(** :ref:`float` r, :ref:`float` g, :ref:`float` b **)** -Constructs a color from an RGB profile using values between 0 and 1. Alpha will always be 1. +Constructs a color from RGB values, typically between 0 and 1. Alpha will be 1. :: - var c = Color(0.2, 1.0, 0.7) # Equivalent to RGBA(51, 255, 178, 255) + var color = Color(0.2, 1.0, 0.7) # Similar to Color8(51, 255, 178, 255) ---- - :ref:`Color` **Color** **(** :ref:`float` r, :ref:`float` g, :ref:`float` b, :ref:`float` a **)** -Constructs a color from an RGBA profile using values between 0 and 1. +Constructs a color from RGBA values, typically between 0 and 1. :: - var c = Color(0.2, 1.0, 0.7, 0.8) # Equivalent to RGBA(51, 255, 178, 204) + var color = Color(0.2, 1.0, 0.7, 0.8) # Similar to Color8(51, 255, 178, 204) ---- @@ -938,8 +949,8 @@ Returns the inverted color ``(1 - r, 1 - g, 1 - b, a)``. :: - var c = Color(0.3, 0.4, 0.9) - var inverted_color = c.inverted() # A color of an RGBA(178, 153, 26, 255) + var color = Color(0.3, 0.4, 0.9) + var inverted_color = color.inverted() # Equivalent to Color(0.7, 0.6, 0.1) ---- @@ -974,7 +985,7 @@ Returns the linear interpolation with another color. The interpolation factor `` var c1 = Color(1.0, 0.0, 0.0) var c2 = Color(0.0, 1.0, 0.0) - var li_c = c1.linear_interpolate(c2, 0.5) # A color of an RGBA(128, 128, 0, 255) + var li_c = c1.linear_interpolate(c2, 0.5) # Equivalent to Color(0.5, 0.5, 0.0) ---- @@ -982,12 +993,12 @@ Returns the linear interpolation with another color. The interpolation factor `` - :ref:`int` **to_abgr32** **(** **)** -Returns the color's 32-bit integer in ABGR format (each byte represents a component of the ABGR profile). ABGR is the reversed version of the default format. +Returns the color converted to a 32-bit integer in ABGR format (each byte represents a color channel). ABGR is the reversed version of the default format. :: - var c = Color(1, 0.5, 0.2) - print(c.to_abgr32()) # Prints 4281565439 + var color = Color(1, 0.5, 0.2) + print(color.to_abgr32()) # Prints 4281565439 ---- @@ -995,12 +1006,12 @@ Returns the color's 32-bit integer in ABGR format (each byte represents a compon - :ref:`int` **to_abgr64** **(** **)** -Returns the color's 64-bit integer in ABGR format (each word represents a component of the ABGR profile). ABGR is the reversed version of the default format. +Returns the color converted to a 64-bit integer in ABGR format (each word represents a color channel). ABGR is the reversed version of the default format. :: - var c = Color(1, 0.5, 0.2) - print(c.to_abgr64()) # Prints -225178692812801 + var color = Color(1, 0.5, 0.2) + print(color.to_abgr64()) # Prints -225178692812801 ---- @@ -1008,12 +1019,12 @@ Returns the color's 64-bit integer in ABGR format (each word represents a compon - :ref:`int` **to_argb32** **(** **)** -Returns the color's 32-bit integer in ARGB format (each byte represents a component of the ARGB profile). ARGB is more compatible with DirectX. +Returns the color converted to a 32-bit integer in ARGB format (each byte represents a color channel). ARGB is more compatible with DirectX. :: - var c = Color(1, 0.5, 0.2) - print(c.to_argb32()) # Prints 4294934323 + var color = Color(1, 0.5, 0.2) + print(color.to_argb32()) # Prints 4294934323 ---- @@ -1021,12 +1032,12 @@ Returns the color's 32-bit integer in ARGB format (each byte represents a compon - :ref:`int` **to_argb64** **(** **)** -Returns the color's 64-bit integer in ARGB format (each word represents a component of the ARGB profile). ARGB is more compatible with DirectX. +Returns the color converted to a 64-bit integer in ARGB format (each word represents a color channel). ARGB is more compatible with DirectX. :: - var c = Color(1, 0.5, 0.2) - print(c.to_argb64()) # Prints -2147470541 + var color = Color(1, 0.5, 0.2) + print(color.to_argb64()) # Prints -2147470541 ---- @@ -1050,12 +1061,12 @@ Setting ``with_alpha`` to ``false`` excludes alpha from the hexadecimal string. - :ref:`int` **to_rgba32** **(** **)** -Returns the color's 32-bit integer in RGBA format (each byte represents a component of the RGBA profile). RGBA is Godot's default format. +Returns the color converted to a 32-bit integer in RGBA format (each byte represents a color channel). RGBA is Godot's default format. :: - var c = Color(1, 0.5, 0.2) - print(c.to_rgba32()) # Prints 4286526463 + var color = Color(1, 0.5, 0.2) + print(color.to_rgba32()) # Prints 4286526463 ---- @@ -1063,12 +1074,12 @@ Returns the color's 32-bit integer in RGBA format (each byte represents a compon - :ref:`int` **to_rgba64** **(** **)** -Returns the color's 64-bit integer in RGBA format (each word represents a component of the RGBA profile). RGBA is Godot's default format. +Returns the color converted to a 64-bit integer in RGBA format (each word represents a color channel). RGBA is Godot's default format. :: - var c = Color(1, 0.5, 0.2) - print(c.to_rgba64()) # Prints -140736629309441 + var color = Color(1, 0.5, 0.2) + print(color.to_rgba64()) # Prints -140736629309441 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_colorpicker.rst b/classes/class_colorpicker.rst index 5ef38730e..baa424584 100644 --- a/classes/class_colorpicker.rst +++ b/classes/class_colorpicker.rst @@ -18,6 +18,11 @@ Description :ref:`Control` node displaying a color picker widget. It's useful for selecting a color from an RGB/RGBA colorspace. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/146 `_ + Properties ---------- diff --git a/classes/class_colorpickerbutton.rst b/classes/class_colorpickerbutton.rst index 088f59d4f..d5203deff 100644 --- a/classes/class_colorpickerbutton.rst +++ b/classes/class_colorpickerbutton.rst @@ -18,6 +18,15 @@ Description Encapsulates a :ref:`ColorPicker` making it accessible by pressing a button. Pressing the button will toggle the :ref:`ColorPicker` visibility. +See also :ref:`BaseButton` which contains common properties and methods associated with this node. + +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/133 `_ + +- `https://godotengine.org/asset-library/asset/517 `_ + Properties ---------- diff --git a/classes/class_colorrect.rst b/classes/class_colorrect.rst index 925c0e7ee..387e5da6b 100644 --- a/classes/class_colorrect.rst +++ b/classes/class_colorrect.rst @@ -16,7 +16,12 @@ Colored rectangle. Description ----------- -Displays a colored rectangle. +Displays a rectangle filled with a solid :ref:`color`. If you need to display the border alone, consider using :ref:`ReferenceRect` instead. + +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/515 `_ Properties ---------- diff --git a/classes/class_concavepolygonshape.rst b/classes/class_concavepolygonshape.rst index 69eeb16b7..1f52e0ef7 100644 --- a/classes/class_concavepolygonshape.rst +++ b/classes/class_concavepolygonshape.rst @@ -20,6 +20,11 @@ Concave polygon shape resource, which can be set into a :ref:`PhysicsBody` nodes like :ref:`StaticBody` and will not work with :ref:`KinematicBody` or :ref:`RigidBody` with a mode other than Static. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/675 `_ + Methods ------- diff --git a/classes/class_conetwistjoint.rst b/classes/class_conetwistjoint.rst index 3376fdfac..47fc9b539 100644 --- a/classes/class_conetwistjoint.rst +++ b/classes/class_conetwistjoint.rst @@ -11,7 +11,7 @@ ConeTwistJoint **Inherits:** :ref:`Joint` **<** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` -A twist joint between two 3D bodies. +A twist joint between two 3D PhysicsBodies. Description ----------- @@ -20,7 +20,7 @@ The joint can rotate the bodies across an axis defined by the local x-axes of th The twist axis is initiated as the X axis of the :ref:`Joint`. -Once the Bodies swing, the twist axis is calculated as the middle of the x-axes of the Joint in the local space of the two Bodies. +Once the Bodies swing, the twist axis is calculated as the middle of the x-axes of the Joint in the local space of the two Bodies. See also :ref:`Generic6DOFJoint`. Properties ---------- diff --git a/classes/class_configfile.rst b/classes/class_configfile.rst index 8e15c7e50..2d15a823d 100644 --- a/classes/class_configfile.rst +++ b/classes/class_configfile.rst @@ -49,6 +49,8 @@ ConfigFiles can also contain manually written comment lines starting with a semi Methods ------- ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`clear` **(** **)** | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`erase_section` **(** :ref:`String` section **)** | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -84,6 +86,12 @@ Methods Method Descriptions ------------------- +.. _class_ConfigFile_method_clear: + +- void **clear** **(** **)** + +---- + .. _class_ConfigFile_method_erase_section: - void **erase_section** **(** :ref:`String` section **)** @@ -174,7 +182,7 @@ Returns one of the :ref:`Error` code constants (``OK`` - :ref:`Error` **parse** **(** :ref:`String` data **)** -Parses the 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. +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. Returns one of the :ref:`Error` code constants (``OK`` on success). diff --git a/classes/class_container.rst b/classes/class_container.rst index 8463982c7..cd1400e9d 100644 --- a/classes/class_container.rst +++ b/classes/class_container.rst @@ -11,7 +11,7 @@ Container **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -**Inherited By:** :ref:`BoxContainer`, :ref:`CenterContainer`, :ref:`EditorProperty`, :ref:`GraphNode`, :ref:`GridContainer`, :ref:`MarginContainer`, :ref:`PanelContainer`, :ref:`ScrollContainer`, :ref:`SplitContainer`, :ref:`TabContainer`, :ref:`ViewportContainer` +**Inherited By:** :ref:`AspectRatioContainer`, :ref:`BoxContainer`, :ref:`CenterContainer`, :ref:`EditorProperty`, :ref:`GraphNode`, :ref:`GridContainer`, :ref:`MarginContainer`, :ref:`PanelContainer`, :ref:`ScrollContainer`, :ref:`SplitContainer`, :ref:`TabContainer`, :ref:`ViewportContainer` Base node for containers. diff --git a/classes/class_control.rst b/classes/class_control.rst index fbbd22f40..2cdd3d4b3 100644 --- a/classes/class_control.rst +++ b/classes/class_control.rst @@ -41,74 +41,80 @@ Tutorials - :doc:`../tutorials/2d/custom_drawing_in_2d` +- :doc:`../tutorials/gui/control_node_gallery` + +- `https://github.com/godotengine/godot-demo-projects/tree/master/gui `_ + Properties ---------- -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :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:`FocusMode` | :ref:`focus_mode` | ``0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`NodePath` | :ref:`focus_neighbour_bottom` | ``NodePath("")`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`NodePath` | :ref:`focus_neighbour_left` | ``NodePath("")`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`NodePath` | :ref:`focus_neighbour_right` | ``NodePath("")`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`NodePath` | :ref:`focus_neighbour_top` | ``NodePath("")`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`NodePath` | :ref:`focus_next` | ``NodePath("")`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`NodePath` | :ref:`focus_previous` | ``NodePath("")`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`GrowDirection` | :ref:`grow_horizontal` | ``1`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`GrowDirection` | :ref:`grow_vertical` | ``1`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`String` | :ref:`hint_tooltip` | ``""`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`margin_bottom` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`margin_left` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`margin_right` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`margin_top` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`CursorShape` | :ref:`mouse_default_cursor_shape` | ``0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`MouseFilter` | :ref:`mouse_filter` | ``0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`bool` | :ref:`rect_clip_content` | ``false`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`rect_global_position` | | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`rect_min_size` | ``Vector2( 0, 0 )`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`rect_pivot_offset` | ``Vector2( 0, 0 )`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`rect_position` | ``Vector2( 0, 0 )`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`rect_rotation` | ``0.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`rect_scale` | ``Vector2( 1, 1 )`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Vector2` | :ref:`rect_size` | ``Vector2( 0, 0 )`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`int` | :ref:`size_flags_horizontal` | ``1`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`float` | :ref:`size_flags_stretch_ratio` | ``1.0`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`int` | :ref:`size_flags_vertical` | ``1`` | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ -| :ref:`Theme` | :ref:`theme` | | -+--------------------------------------------------+--------------------------------------------------------------------------------------+---------------------+ ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :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:`FocusMode` | :ref:`focus_mode` | ``0`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`NodePath` | :ref:`focus_neighbour_bottom` | ``NodePath("")`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`NodePath` | :ref:`focus_neighbour_left` | ``NodePath("")`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`NodePath` | :ref:`focus_neighbour_right` | ``NodePath("")`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`NodePath` | :ref:`focus_neighbour_top` | ``NodePath("")`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`NodePath` | :ref:`focus_next` | ``NodePath("")`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`NodePath` | :ref:`focus_previous` | ``NodePath("")`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`GrowDirection` | :ref:`grow_horizontal` | ``1`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`GrowDirection` | :ref:`grow_vertical` | ``1`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`String` | :ref:`hint_tooltip` | ``""`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`bool` | :ref:`input_pass_on_modal_close_click` | ``true`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`float` | :ref:`margin_bottom` | ``0.0`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`float` | :ref:`margin_left` | ``0.0`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`float` | :ref:`margin_right` | ``0.0`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`float` | :ref:`margin_top` | ``0.0`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`CursorShape` | :ref:`mouse_default_cursor_shape` | ``0`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`MouseFilter` | :ref:`mouse_filter` | ``0`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`bool` | :ref:`rect_clip_content` | ``false`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`Vector2` | :ref:`rect_global_position` | | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`Vector2` | :ref:`rect_min_size` | ``Vector2( 0, 0 )`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`Vector2` | :ref:`rect_pivot_offset` | ``Vector2( 0, 0 )`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`Vector2` | :ref:`rect_position` | ``Vector2( 0, 0 )`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`float` | :ref:`rect_rotation` | ``0.0`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`Vector2` | :ref:`rect_scale` | ``Vector2( 1, 1 )`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`Vector2` | :ref:`rect_size` | ``Vector2( 0, 0 )`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`int` | :ref:`size_flags_horizontal` | ``1`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`float` | :ref:`size_flags_stretch_ratio` | ``1.0`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`int` | :ref:`size_flags_vertical` | ``1`` | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ +| :ref:`Theme` | :ref:`theme` | | ++--------------------------------------------------+------------------------------------------------------------------------------------------------+---------------------+ Methods ------- @@ -120,7 +126,7 @@ Methods +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_gui_input` **(** :ref:`InputEvent` event **)** |virtual| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Object` | :ref:`_make_custom_tooltip` **(** :ref:`String` for_text **)** |virtual| | +| :ref:`Control` | :ref:`_make_custom_tooltip` **(** :ref:`String` for_text **)** |virtual| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`accept_event` **(** **)** | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -140,17 +146,21 @@ Methods +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`drop_data` **(** :ref:`Vector2` position, :ref:`Variant` data **)** |virtual| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Control` | :ref:`find_next_valid_focus` **(** **)** |const| | ++----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Control` | :ref:`find_prev_valid_focus` **(** **)** |const| | ++----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`force_drag` **(** :ref:`Variant` data, :ref:`Control` preview **)** | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_anchor` **(** :ref:`Margin` margin **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`get_begin` **(** **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`get_color` **(** :ref:`String` name, :ref:`String` type="" **)** |const| | +| :ref:`Color` | :ref:`get_color` **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`get_combined_minimum_size` **(** **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_constant` **(** :ref:`String` name, :ref:`String` type="" **)** |const| | +| :ref:`int` | :ref:`get_constant` **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`CursorShape` | :ref:`get_cursor_shape` **(** :ref:`Vector2` position=Vector2( 0, 0 ) **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -162,11 +172,11 @@ Methods +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Control` | :ref:`get_focus_owner` **(** **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Font` | :ref:`get_font` **(** :ref:`String` name, :ref:`String` type="" **)** |const| | +| :ref:`Font` | :ref:`get_font` **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Rect2` | :ref:`get_global_rect` **(** **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Texture` | :ref:`get_icon` **(** :ref:`String` name, :ref:`String` type="" **)** |const| | +| :ref:`Texture` | :ref:`get_icon` **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_margin` **(** :ref:`Margin` margin **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -180,7 +190,7 @@ Methods +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_rotation` **(** **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StyleBox` | :ref:`get_stylebox` **(** :ref:`String` name, :ref:`String` type="" **)** |const| | +| :ref:`StyleBox` | :ref:`get_stylebox` **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_tooltip` **(** :ref:`Vector2` at_position=Vector2( 0, 0 ) **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -188,21 +198,21 @@ Methods +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`grab_focus` **(** **)** | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_color` **(** :ref:`String` name, :ref:`String` type="" **)** |const| | +| :ref:`bool` | :ref:`has_color` **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_color_override` **(** :ref:`String` name **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_constant` **(** :ref:`String` name, :ref:`String` type="" **)** |const| | +| :ref:`bool` | :ref:`has_constant` **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_constant_override` **(** :ref:`String` name **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_focus` **(** **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_font` **(** :ref:`String` name, :ref:`String` type="" **)** |const| | +| :ref:`bool` | :ref:`has_font` **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_font_override` **(** :ref:`String` name **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_icon` **(** :ref:`String` name, :ref:`String` type="" **)** |const| | +| :ref:`bool` | :ref:`has_icon` **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_icon_override` **(** :ref:`String` name **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -210,7 +220,7 @@ Methods +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_shader_override` **(** :ref:`String` name **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_stylebox` **(** :ref:`String` name, :ref:`String` type="" **)** |const| | +| :ref:`bool` | :ref:`has_stylebox` **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_stylebox_override` **(** :ref:`String` name **)** |const| | +----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -845,6 +855,35 @@ Controls the direction on the vertical axis in which the control should grow if Changes the 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`. You can change the time required for the tooltip to appear with ``gui/timers/tooltip_delay_sec`` option in Project Settings. +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: + +:: + + var style_box = StyleBoxFlat.new() + style_box.set_bg_color(Color(1, 1, 0)) + style_box.set_border_width_all(2) + # We assume here that the `theme` property has been assigned a custom Theme beforehand. + theme.set_stylebox("panel", "TooltipPanel", style_box) + theme.set_color("font_color", "TooltipLabel", Color(0, 1, 1)) + +---- + +.. _class_Control_property_input_pass_on_modal_close_click: + +- :ref:`bool` **input_pass_on_modal_close_click** + ++-----------+--------------------------------------+ +| *Default* | ``true`` | ++-----------+--------------------------------------+ +| *Setter* | set_pass_on_modal_close_click(value) | ++-----------+--------------------------------------+ +| *Getter* | get_pass_on_modal_close_click() | ++-----------+--------------------------------------+ + +Enables whether input should propagate when you close the control as modal. + +If ``false``, stops event handling at the viewport input event handling. The viewport first hides the modal and after marks the input as handled. + ---- .. _class_Control_property_margin_bottom: @@ -1057,7 +1096,7 @@ The node's rotation around its pivot, in degrees. See :ref:`rect_pivot_offset`. Change this property to scale the node around its :ref:`rect_pivot_offset`. The Control's :ref:`hint_tooltip` will also scale according to this value. -**Note:** This property is mainly intended to be used for animation purposes. Text inside the Control will look pixelated or blurry when the Control is scaled. To support multiple resolutions in your project, use an appropriate viewport stretch mode as described in the `documentation `_ instead of scaling Controls individually. +**Note:** This property is mainly intended to be used for animation purposes. Text inside the Control will look pixelated or blurry when the Control is scaled. To support multiple resolutions in your project, use an appropriate viewport stretch mode as described in the `documentation `_ instead of scaling Controls individually. **Note:** If the Control node is a child of a :ref:`Container` node, the scale will be reset to ``Vector2(1, 1)`` when the scene is instanced. To set the Control's scale when it's instanced, wait for one frame using ``yield(get_tree(), "idle_frame")`` then set its :ref:`rect_scale` property. @@ -1191,15 +1230,17 @@ The event won't trigger if: .. _class_Control_method__make_custom_tooltip: -- :ref:`Object` **_make_custom_tooltip** **(** :ref:`String` for_text **)** |virtual| +- :ref:`Control` **_make_custom_tooltip** **(** :ref:`String` for_text **)** |virtual| -Virtual method to be implemented by the user. Returns a ``Control`` node that should be used as a tooltip instead of the default one. Use ``for_text`` parameter to determine what text the tooltip should contain (likely the contents of :ref:`hint_tooltip`). +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:`hint_tooltip` property. -The returned node must be of type ``Control`` or Control-derieved. It can have child nodes of any type. It is freed when the tooltip disappears, so make sure you always provide a new instance, not e.g. a node from scene. When ``null`` or non-Control node is returned, the default tooltip will be used instead. +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:`hint_tooltip` 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:`rect_min_size` to some non-zero value. -Example of usage with custom-constructed node: +Example of usage with a custom-constructed node: :: @@ -1208,12 +1249,12 @@ Example of usage with custom-constructed node: label.text = for_text return label -Example of usage with custom scene instance: +Example of usage with a custom scene instance: :: func _make_custom_tooltip(for_text): - var tooltip = preload("SomeTooltipScene.tscn").instance() + var tooltip = preload("res://SomeTooltipScene.tscn").instance() tooltip.get_node("Label").text = for_text return tooltip @@ -1336,6 +1377,22 @@ Godot calls this method to pass you the ``data`` from a control's :ref:`get_drag ---- +.. _class_Control_method_find_next_valid_focus: + +- :ref:`Control` **find_next_valid_focus** **(** **)** |const| + +Finds the next (below in the tree) ``Control`` that can receive the focus. + +---- + +.. _class_Control_method_find_prev_valid_focus: + +- :ref:`Control` **find_prev_valid_focus** **(** **)** |const| + +Finds the previous (above in the tree) ``Control`` that can receive the focus. + +---- + .. _class_Control_method_force_drag: - void **force_drag** **(** :ref:`Variant` data, :ref:`Control` preview **)** @@ -1364,9 +1421,9 @@ Returns :ref:`margin_left` and :ref:`margin_ .. _class_Control_method_get_color: -- :ref:`Color` **get_color** **(** :ref:`String` name, :ref:`String` type="" **)** |const| +- :ref:`Color` **get_color** **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| -Returns a color from assigned :ref:`Theme` with given ``name`` and associated with ``Control`` of given ``type``. +Returns a color from assigned :ref:`Theme` with given ``name`` and associated with ``Control`` of given ``node_type``. :: @@ -1385,9 +1442,9 @@ Returns combined minimum size from :ref:`rect_min_size` **get_constant** **(** :ref:`String` name, :ref:`String` type="" **)** |const| +- :ref:`int` **get_constant** **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| -Returns a constant from assigned :ref:`Theme` with given ``name`` and associated with ``Control`` of given ``type``. +Returns a constant from assigned :ref:`Theme` with given ``name`` and associated with ``Control`` of given ``node_type``. ---- @@ -1442,9 +1499,9 @@ Returns the control that has the keyboard focus or ``null`` if none. .. _class_Control_method_get_font: -- :ref:`Font` **get_font** **(** :ref:`String` name, :ref:`String` type="" **)** |const| +- :ref:`Font` **get_font** **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| -Returns a font from assigned :ref:`Theme` with given ``name`` and associated with ``Control`` of given ``type``. +Returns a font from assigned :ref:`Theme` with given ``name`` and associated with ``Control`` of given ``node_type``. ---- @@ -1458,9 +1515,9 @@ Returns the position and size of the control relative to the top-left corner of .. _class_Control_method_get_icon: -- :ref:`Texture` **get_icon** **(** :ref:`String` name, :ref:`String` type="" **)** |const| +- :ref:`Texture` **get_icon** **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| -Returns an icon from assigned :ref:`Theme` with given ``name`` and associated with ``Control`` of given ``type``. +Returns an icon from assigned :ref:`Theme` with given ``name`` and associated with ``Control`` of given ``node_type``. ---- @@ -1514,9 +1571,9 @@ Returns the rotation (in radians). .. _class_Control_method_get_stylebox: -- :ref:`StyleBox` **get_stylebox** **(** :ref:`String` name, :ref:`String` type="" **)** |const| +- :ref:`StyleBox` **get_stylebox** **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| -Returns a :ref:`StyleBox` from assigned :ref:`Theme` with given ``name`` and associated with ``Control`` of given ``type``. +Returns a :ref:`StyleBox` from assigned :ref:`Theme` with given ``name`` and associated with ``Control`` of given ``node_type``. ---- @@ -1551,9 +1608,9 @@ Steal the focus from another control and become the focused control (see :ref:`f .. _class_Control_method_has_color: -- :ref:`bool` **has_color** **(** :ref:`String` name, :ref:`String` type="" **)** |const| +- :ref:`bool` **has_color** **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| -Returns ``true`` if :ref:`Color` with given ``name`` and associated with ``Control`` of given ``type`` exists in assigned :ref:`Theme`. +Returns ``true`` if :ref:`Color` with given ``name`` and associated with ``Control`` of given ``node_type`` exists in assigned :ref:`Theme`. ---- @@ -1567,9 +1624,9 @@ Returns ``true`` if :ref:`Color` with given ``name`` has a valid ov .. _class_Control_method_has_constant: -- :ref:`bool` **has_constant** **(** :ref:`String` name, :ref:`String` type="" **)** |const| +- :ref:`bool` **has_constant** **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| -Returns ``true`` if constant with given ``name`` and associated with ``Control`` of given ``type`` exists in assigned :ref:`Theme`. +Returns ``true`` if constant with given ``name`` and associated with ``Control`` of given ``node_type`` exists in assigned :ref:`Theme`. ---- @@ -1591,9 +1648,9 @@ Returns ``true`` if this is the current focused control. See :ref:`focus_mode` **has_font** **(** :ref:`String` name, :ref:`String` type="" **)** |const| +- :ref:`bool` **has_font** **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| -Returns ``true`` if font with given ``name`` and associated with ``Control`` of given ``type`` exists in assigned :ref:`Theme`. +Returns ``true`` if font with given ``name`` and associated with ``Control`` of given ``node_type`` exists in assigned :ref:`Theme`. ---- @@ -1607,9 +1664,9 @@ Returns ``true`` if font with given ``name`` has a valid override in this ``Cont .. _class_Control_method_has_icon: -- :ref:`bool` **has_icon** **(** :ref:`String` name, :ref:`String` type="" **)** |const| +- :ref:`bool` **has_icon** **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| -Returns ``true`` if icon with given ``name`` and associated with ``Control`` of given ``type`` exists in assigned :ref:`Theme`. +Returns ``true`` if icon with given ``name`` and associated with ``Control`` of given ``node_type`` exists in assigned :ref:`Theme`. ---- @@ -1643,9 +1700,9 @@ Returns ``true`` if :ref:`Shader` with given ``name`` has a valid .. _class_Control_method_has_stylebox: -- :ref:`bool` **has_stylebox** **(** :ref:`String` name, :ref:`String` type="" **)** |const| +- :ref:`bool` **has_stylebox** **(** :ref:`String` name, :ref:`String` node_type="" **)** |const| -Returns ``true`` if :ref:`StyleBox` with given ``name`` and associated with ``Control`` of given ``type`` exists in assigned :ref:`Theme`. +Returns ``true`` if :ref:`StyleBox` with given ``name`` and associated with ``Control`` of given ``node_type`` exists in assigned :ref:`Theme`. ---- @@ -1756,7 +1813,7 @@ Forwarding can be implemented in the target control similar to the methods :ref: - void **set_drag_preview** **(** :ref:`Control` control **)** -Shows the given control at the mouse pointer. A good time to call this method is in :ref:`get_drag_data`. The control must not be in the scene tree. +Shows the given control at the mouse pointer. A good time to call this method is in :ref:`get_drag_data`. The control must not be in the scene tree. You should not free the control, and you should not keep a reference to the control beyond the duration of the drag. It will be deleted automatically after the drag has ended. :: diff --git a/classes/class_convexpolygonshape.rst b/classes/class_convexpolygonshape.rst index 6be949045..92bf262e0 100644 --- a/classes/class_convexpolygonshape.rst +++ b/classes/class_convexpolygonshape.rst @@ -18,6 +18,11 @@ Description Convex polygon shape resource, which can be added to a :ref:`PhysicsBody` or area. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/675 `_ + Properties ---------- diff --git a/classes/class_cpuparticles.rst b/classes/class_cpuparticles.rst index ff79ab71c..e542e6252 100644 --- a/classes/class_cpuparticles.rst +++ b/classes/class_cpuparticles.rst @@ -20,6 +20,8 @@ CPU-based 3D particle node used to create a variety of particle systems and effe See also :ref:`Particles`, which provides the same functionality with hardware acceleration, but may not run on older devices. +**Note:** Unlike :ref:`Particles`, the visibility rect is generated on-the-fly and doesn't need to be configured by the user. + Properties ---------- @@ -322,7 +324,9 @@ Property Descriptions | *Getter* | get_amount() | +-----------+-------------------+ -Number of particles emitted in one emission cycle. +The number of particles emitted in one emission cycle (corresponding to the :ref:`lifetime`). + +**Note:** Changing :ref:`amount` will reset the particle emission, therefore removing all particles that were already emitted before changing :ref:`amount`. ---- @@ -942,7 +946,7 @@ Initial velocity randomness ratio. | *Getter* | get_lifetime() | +-----------+---------------------+ -Amount of time each particle will exist. +The amount of time each particle will exist (in seconds). ---- diff --git a/classes/class_cpuparticles2d.rst b/classes/class_cpuparticles2d.rst index 9fe372458..8e7a9b9ce 100644 --- a/classes/class_cpuparticles2d.rst +++ b/classes/class_cpuparticles2d.rst @@ -20,6 +20,8 @@ CPU-based 2D particle node used to create a variety of particle systems and effe See also :ref:`Particles2D`, which provides the same functionality with hardware acceleration, but may not run on older devices. +**Note:** Unlike :ref:`Particles2D`, the visibility rect is generated on-the-fly and doesn't need to be configured by the user. + Tutorials --------- @@ -319,7 +321,9 @@ Property Descriptions | *Getter* | get_amount() | +-----------+-------------------+ -Number of particles emitted in one emission cycle. +The number of particles emitted in one emission cycle (corresponding to the :ref:`lifetime`). + +**Note:** Changing :ref:`amount` will reset the particle emission, therefore removing all particles that were already emitted before changing :ref:`amount`. ---- @@ -887,7 +891,7 @@ Initial velocity randomness ratio. | *Getter* | get_lifetime() | +-----------+---------------------+ -Amount of time each particle will exist. +The amount of time each particle will exist (in seconds). ---- diff --git a/classes/class_csgshape.rst b/classes/class_csgshape.rst index 5116ca1c0..1b6a48d22 100644 --- a/classes/class_csgshape.rst +++ b/classes/class_csgshape.rst @@ -108,7 +108,7 @@ The physics layers this area is in. Collidable objects can exist in any of 32 different layers. These layers work like a tagging system, and are not visual. A collidable can use these layers to select with which objects it can collide, using the collision_mask property. -A contact is detected if object A is in any of the layers that object B scans, or object B is in any layer scanned by object A. See `Collision layers and masks `_ in the documentation for more information. +A contact is detected if object A is in any of the layers that object B scans, or object B is in any layer scanned by object A. See `Collision layers and masks `_ in the documentation for more information. ---- @@ -124,7 +124,7 @@ A contact is detected if object A is in any of the layers that object B scans, o | *Getter* | get_collision_mask() | +-----------+---------------------------+ -The physics layers this CSG shape scans for collisions. See `Collision layers and masks `_ in the documentation for more information. +The physics layers this CSG shape scans for collisions. See `Collision layers and masks `_ in the documentation for more information. ---- diff --git a/classes/class_cubemesh.rst b/classes/class_cubemesh.rst index bcfea0e69..4970364ff 100644 --- a/classes/class_cubemesh.rst +++ b/classes/class_cubemesh.rst @@ -20,6 +20,8 @@ Generate an axis-aligned cuboid :ref:`PrimitiveMesh`. The cube's UV layout is arranged in a 3×2 layout that allows texturing each face individually. To apply the same texture on all faces, change the material's UV property to ``Vector3(3, 2, 1)``. +**Note:** When using a large textured ``CubeMesh`` (e.g. as a floor), you may stumble upon UV jittering issues depending on the camera angle. To solve this, increase :ref:`subdivide_depth`, :ref:`subdivide_height` and :ref:`subdivide_width` until you no longer notice UV jittering. + Properties ---------- diff --git a/classes/class_curve2d.rst b/classes/class_curve2d.rst index 65bd4ac0d..81b586d3b 100644 --- a/classes/class_curve2d.rst +++ b/classes/class_curve2d.rst @@ -136,7 +136,7 @@ Returns the closest offset to ``to_point``. This offset is meant to be used in : - :ref:`Vector2` **get_closest_point** **(** :ref:`Vector2` to_point **)** |const| -Returns the closest point (in curve's local space) to ``to_point``. +Returns the closest baked point (in curve's local space) to ``to_point``. ``to_point`` must be in this curve's local space. @@ -154,7 +154,7 @@ Returns the number of points describing the curve. - :ref:`Vector2` **get_point_in** **(** :ref:`int` idx **)** |const| -Returns the position of the control point leading to the vertex ``idx``. If the index is out of bounds, the function sends an error to the console, and returns ``(0, 0)``. +Returns the position of the control point leading to the vertex ``idx``. The returned position is relative to the vertex ``idx``. If the index is out of bounds, the function sends an error to the console, and returns ``(0, 0)``. ---- @@ -162,7 +162,7 @@ Returns the position of the control point leading to the vertex ``idx``. If the - :ref:`Vector2` **get_point_out** **(** :ref:`int` idx **)** |const| -Returns the position of the control point leading out of the vertex ``idx``. If the index is out of bounds, the function sends an error to the console, and returns ``(0, 0)``. +Returns the position of the control point leading out of the vertex ``idx``. The returned position is relative to the vertex ``idx``. If the index is out of bounds, the function sends an error to the console, and returns ``(0, 0)``. ---- @@ -216,7 +216,7 @@ Deletes the point ``idx`` from the curve. Sends an error to the console if ``idx - void **set_point_in** **(** :ref:`int` idx, :ref:`Vector2` position **)** -Sets the position of the control point leading to the vertex ``idx``. If the index is out of bounds, the function sends an error to the console. +Sets the position of the control point leading to the vertex ``idx``. If the index is out of bounds, the function sends an error to the console. The position is relative to the vertex. ---- @@ -224,7 +224,7 @@ Sets the position of the control point leading to the vertex ``idx``. If the ind - void **set_point_out** **(** :ref:`int` idx, :ref:`Vector2` position **)** -Sets the position of the control point leading out of the vertex ``idx``. If the index is out of bounds, the function sends an error to the console. +Sets the position of the control point leading out of the vertex ``idx``. If the index is out of bounds, the function sends an error to the console. The position is relative to the vertex. ---- diff --git a/classes/class_curve3d.rst b/classes/class_curve3d.rst index 32fbf61ae..41da07759 100644 --- a/classes/class_curve3d.rst +++ b/classes/class_curve3d.rst @@ -182,7 +182,7 @@ Returns the closest offset to ``to_point``. This offset is meant to be used in : - :ref:`Vector3` **get_closest_point** **(** :ref:`Vector3` to_point **)** |const| -Returns the closest point (in curve's local space) to ``to_point``. +Returns the closest baked point (in curve's local space) to ``to_point``. ``to_point`` must be in this curve's local space. @@ -200,7 +200,7 @@ Returns the number of points describing the curve. - :ref:`Vector3` **get_point_in** **(** :ref:`int` idx **)** |const| -Returns the position of the control point leading to the vertex ``idx``. If the index is out of bounds, the function sends an error to the console, and returns ``(0, 0, 0)``. +Returns the position of the control point leading to the vertex ``idx``. The returned position is relative to the vertex ``idx``. If the index is out of bounds, the function sends an error to the console, and returns ``(0, 0, 0)``. ---- @@ -208,7 +208,7 @@ Returns the position of the control point leading to the vertex ``idx``. If the - :ref:`Vector3` **get_point_out** **(** :ref:`int` idx **)** |const| -Returns the position of the control point leading out of the vertex ``idx``. If the index is out of bounds, the function sends an error to the console, and returns ``(0, 0, 0)``. +Returns the position of the control point leading out of the vertex ``idx``. The returned position is relative to the vertex ``idx``. If the index is out of bounds, the function sends an error to the console, and returns ``(0, 0, 0)``. ---- @@ -242,7 +242,7 @@ If ``idx`` is out of bounds it is truncated to the first or last vertex, and ``t - :ref:`Vector3` **interpolate_baked** **(** :ref:`float` offset, :ref:`bool` cubic=false **)** |const| -Returns a point within the curve at position ``offset``, where ``offset`` is measured as a pixel distance along the curve. +Returns a point within the curve at position ``offset``, where ``offset`` is measured as a distance in 3D units along the curve. To do that, it finds the two cached points where the ``offset`` lies between, then interpolates the values. This interpolation is cubic if ``cubic`` is set to ``true``, or linear if set to ``false``. @@ -282,7 +282,7 @@ Deletes the point ``idx`` from the curve. Sends an error to the console if ``idx - void **set_point_in** **(** :ref:`int` idx, :ref:`Vector3` position **)** -Sets the position of the control point leading to the vertex ``idx``. If the index is out of bounds, the function sends an error to the console. +Sets the position of the control point leading to the vertex ``idx``. If the index is out of bounds, the function sends an error to the console. The position is relative to the vertex. ---- @@ -290,7 +290,7 @@ Sets the position of the control point leading to the vertex ``idx``. If the ind - void **set_point_out** **(** :ref:`int` idx, :ref:`Vector3` position **)** -Sets the position of the control point leading out of the vertex ``idx``. If the index is out of bounds, the function sends an error to the console. +Sets the position of the control point leading out of the vertex ``idx``. If the index is out of bounds, the function sends an error to the console. The position is relative to the vertex. ---- diff --git a/classes/class_cylindershape.rst b/classes/class_cylindershape.rst index 0ab8acc78..4f0549bea 100644 --- a/classes/class_cylindershape.rst +++ b/classes/class_cylindershape.rst @@ -18,6 +18,15 @@ Description Cylinder shape for collisions. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/678 `_ + +- `https://godotengine.org/asset-library/asset/675 `_ + +- `https://godotengine.org/asset-library/asset/676 `_ + Properties ---------- diff --git a/classes/class_dictionary.rst b/classes/class_dictionary.rst index 2b5eb48bc..e7f6fdb70 100644 --- a/classes/class_dictionary.rst +++ b/classes/class_dictionary.rst @@ -14,7 +14,7 @@ Dictionary type. Description ----------- -Dictionary type. Associative container which contains values referenced by unique keys. Dictionaries are composed of pairs of keys (which must be unique) and values. Dictionaries will preserve the insertion order when adding elements, even though this may not be reflected when printing the dictionary. In other programming languages, this data structure is sometimes referred to as an hash map or associative array. +Dictionary type. Associative container which contains values referenced by unique keys. Dictionaries are composed of pairs of keys (which must be unique) and values. Dictionaries will preserve the insertion order when adding elements, even though this may not be reflected when printing the dictionary. In other programming languages, this data structure is sometimes referred to as a hash map or associative array. You can define a dictionary by placing a comma-separated list of ``key: value`` pairs in curly braces ``{}``. @@ -26,24 +26,34 @@ Creating a dictionary: :: - var my_dir = {} # Creates an empty dictionary. - var points_dir = {"White": 50, "Yellow": 75, "Orange": 100} - var another_dir = { - key1: value1, - key2: value2, - key3: value3, + var my_dict = {} # Creates an empty dictionary. + + var dict_variable_key = "Another key name" + var dict_variable_value = "value2" + var another_dict = { + "Some key name": "value1", + dict_variable_key: dict_variable_value, + } + + var points_dict = {"White": 50, "Yellow": 75, "Orange": 100} + + # Alternative Lua-style syntax. + # Doesn't require quotes around keys, but only string constants can be used as key names. + # Additionally, key names must start with a letter or an underscore. + # Here, `some_key` is a string literal, not a variable! + another_dict = { + some_key = 42, } You can access a dictionary's values by referencing the appropriate key. In the above example, ``points_dir["White"]`` will return ``50``. You can also write ``points_dir.White``, which is equivalent. However, you'll have to use the bracket syntax if the key you're accessing the dictionary with isn't a fixed string (such as a number or variable). :: - export(String, "White", "Yellow", "Orange") var my_color - var points_dir = {"White": 50, "Yellow": 75, "Orange": 100} - + export(string, "White", "Yellow", "Orange") var my_color + var points_dict = {"White": 50, "Yellow": 75, "Orange": 100} func _ready(): # We can't use dot syntax here as `my_color` is a variable. - var points = points_dir[my_color] + var points = points_dict[my_color] In the above code, ``points`` will be assigned the value that is paired with the appropriate color selected in ``my_color``. @@ -51,14 +61,14 @@ Dictionaries can contain more complex data: :: - my_dir = {"First Array": [1, 2, 3, 4]} # Assigns an Array to a String key. + my_dict = {"First Array": [1, 2, 3, 4]} # Assigns an Array to a String key. To add a key to an existing dictionary, access it like an existing key and assign to it: :: - var points_dir = {"White": 50, "Yellow": 75, "Orange": 100} - points_dir["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value. + var points_dict = {"White": 50, "Yellow": 75, "Orange": 100} + points_dict["Blue"] = 150 # Add "Blue" as a key and assign 150 as its value. Finally, dictionaries can contain different types of keys and values in the same dictionary: @@ -67,11 +77,11 @@ Finally, dictionaries can contain different types of keys and values in the same # This is a valid dictionary. # To access the string "Nested value" below, use `my_dir.sub_dir.sub_key` or `my_dir["sub_dir"]["sub_key"]`. # Indexing styles can be mixed and matched depending on your needs. - var my_dir = { + var my_dict = { "String Key": 5, 4: [1, 2, 3], 7: "Hello", - "sub_dir": {"sub_key": "Nested value"}, + "sub_dict": {"sub_key": "Nested value"}, } **Note:** Unlike :ref:`Array`\ s, you can't compare dictionaries directly: @@ -84,27 +94,33 @@ Finally, dictionaries can contain different types of keys and values in the same func compare_arrays(): print(array1 == array2) # Will print true. - dir1 = {"a": 1, "b": 2, "c": 3} - dir2 = {"a": 1, "b": 2, "c": 3} + var dict1 = {"a": 1, "b": 2, "c": 3} + var dict2 = {"a": 1, "b": 2, "c": 3} func compare_dictionaries(): - print(dir1 == dir2) # Will NOT print true. + print(dict1 == dict2) # Will NOT print true. You need to first calculate the dictionary's hash with :ref:`hash` before you can compare them: :: - dir1 = {"a": 1, "b": 2, "c": 3} - dir2 = {"a": 1, "b": 2, "c": 3} + var dict1 = {"a": 1, "b": 2, "c": 3} + var dict2 = {"a": 1, "b": 2, "c": 3} func compare_dictionaries(): - print(dir1.hash() == dir2.hash()) # Will print true. + print(dict1.hash() == dict2.hash()) # Will print true. + +**Note:** When declaring a dictionary with ``const``, the dictionary itself can still be mutated by defining the values of individual keys. Using ``const`` will only prevent assigning the constant with another value after it was initialized. Tutorials --------- - `#dictionary <../getting_started/scripting/gdscript/gdscript_basics.html#dictionary>`_ in :doc:`../getting_started/scripting/gdscript/gdscript_basics` +- `https://godotengine.org/asset-library/asset/676 `_ + +- `https://godotengine.org/asset-library/asset/677 `_ + Methods ------- @@ -197,7 +213,7 @@ This method (like the ``in`` operator) will evaluate to ``true`` as long as the - :ref:`bool` **has_all** **(** :ref:`Array` keys **)** -Returns ``true`` if the dictionary has all of the keys in the given array. +Returns ``true`` if the dictionary has all the keys in the given array. ---- @@ -230,7 +246,7 @@ Returns the list of keys in the ``Dictionary``. - :ref:`int` **size** **(** **)** -Returns the size of the dictionary (in pairs). +Returns the number of keys in the dictionary. ---- diff --git a/classes/class_directory.rst b/classes/class_directory.rst index 90d257c5f..d7f5f7402 100644 --- a/classes/class_directory.rst +++ b/classes/class_directory.rst @@ -20,6 +20,8 @@ Directory type. It is used to manage directories and their content (not restrict When creating a new ``Directory``, its default opened directory will be ``res://``. This may change in the future, so it is advised to always use :ref:`open` to initialize your ``Directory`` where you want to operate, with explicit error checking. +**Note:** Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. Use :ref:`ResourceLoader` to access imported resources. + Here is an example on how to iterate through the files of a directory: :: @@ -151,7 +153,7 @@ Returns the currently opened directory's drive index. See :ref:`get_drive` **get_drive** **(** :ref:`int` idx **)** -On Windows, returns the name of the drive (partition) passed as an argument (e.g. ``C:``). On other platforms, or if the requested drive does not existed, the method returns an empty String. +On Windows, returns the name of the drive (partition) passed as an argument (e.g. ``C:``). On other platforms, or if the requested drive does not exist, the method returns an empty String. ---- @@ -197,7 +199,7 @@ If ``skip_hidden`` is ``true``, hidden files are filtered out. - void **list_dir_end** **(** **)** -Closes the current stream opened with :ref:`list_dir_begin` (whether it has been fully processed with :ref:`get_next` or not does not matter). +Closes the current stream opened with :ref:`list_dir_begin` (whether it has been fully processed with :ref:`get_next` does not matter). ---- diff --git a/classes/class_dynamicfont.rst b/classes/class_dynamicfont.rst index ccdc337d3..90f154d8e 100644 --- a/classes/class_dynamicfont.rst +++ b/classes/class_dynamicfont.rst @@ -29,6 +29,11 @@ DynamicFont uses the `FreeType `_ library for rasteri **Note:** DynamicFont doesn't support features such as kerning, right-to-left typesetting, ligatures, text shaping, variable fonts and optional font features yet. If you wish to "bake" an optional font feature into a TTF font file, you can use `FontForge `_ to do so. In FontForge, use **File > Generate Fonts**, click **Options**, choose the desired features then generate the font. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/676 `_ + Properties ---------- @@ -94,9 +99,9 @@ enum **SpacingType**: - **SPACING_BOTTOM** = **1** --- Spacing at the bottom. -- **SPACING_CHAR** = **2** --- Character spacing. +- **SPACING_CHAR** = **2** --- Spacing for each character. -- **SPACING_SPACE** = **3** --- Space spacing. +- **SPACING_SPACE** = **3** --- Spacing for the space character. Property Descriptions --------------------- @@ -129,7 +134,9 @@ Extra spacing at the bottom in pixels. | *Getter* | get_spacing() | +-----------+--------------------+ -Extra character spacing in pixels. +Extra spacing for each character in pixels. + +This can be a negative number to make the distance between characters smaller. ---- @@ -145,7 +152,9 @@ Extra character spacing in pixels. | *Getter* | get_spacing() | +-----------+--------------------+ -Extra space spacing in pixels. +Extra spacing for the space character (in addition to :ref:`extra_spacing_char`) in pixels. + +This can be a negative number to make the distance between words smaller. ---- diff --git a/classes/class_dynamicfontdata.rst b/classes/class_dynamicfontdata.rst index a372ad3a6..22ee44141 100644 --- a/classes/class_dynamicfontdata.rst +++ b/classes/class_dynamicfontdata.rst @@ -18,6 +18,11 @@ Description Used with :ref:`DynamicFont` to describe the location of a vector font file for dynamic rendering at runtime. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/676 `_ + Properties ---------- diff --git a/classes/class_editorexportplugin.rst b/classes/class_editorexportplugin.rst index fbe5b2fb0..742d12104 100644 --- a/classes/class_editorexportplugin.rst +++ b/classes/class_editorexportplugin.rst @@ -11,7 +11,12 @@ EditorExportPlugin **Inherits:** :ref:`Reference` **<** :ref:`Object` -A script that is executed when exporting projects. +A script that is executed when exporting the project. + +Description +----------- + +Editor export plugins are automatically activated whenever the user exports the project. Their most common use is to determine what files are being included in the exported project. For each plugin, :ref:`_export_begin` is called at the beginning of the export process and then :ref:`_export_file` is called for each exported file. Methods ------- @@ -51,7 +56,7 @@ Method Descriptions - void **_export_begin** **(** :ref:`PoolStringArray` features, :ref:`bool` is_debug, :ref:`String` path, :ref:`int` flags **)** |virtual| -Virtual method to be overridden by the user. It is called when the export starts and provides all information about the export. +Virtual method to be overridden by the user. It is called when the export starts and provides all information about the export. ``features`` is the list of features for the export, ``is_debug`` is ``true`` for debug builds, ``path`` is the target path for the exported project. ``flags`` is only used when running a runnable profile, e.g. when using native run on Android. ---- @@ -67,24 +72,34 @@ Virtual method to be overridden by the user. Called when the export is finished. - void **_export_file** **(** :ref:`String` path, :ref:`String` type, :ref:`PoolStringArray` features **)** |virtual| +Virtual method to be overridden by the user. Called for each exported file, providing arguments that can be used to identify the file. ``path`` is the path of the file, ``type`` is the :ref:`Resource` represented by the file (e.g. :ref:`PackedScene`) and ``features`` is the list of features for the export. + +Calling :ref:`skip` inside this callback will make the file not included in the export. + ---- .. _class_EditorExportPlugin_method_add_file: - void **add_file** **(** :ref:`String` path, :ref:`PoolByteArray` file, :ref:`bool` remap **)** +Adds a custom file to be exported. ``path`` is the virtual path that can be used to load the file, ``file`` is the binary data of the file. If ``remap`` is ``true``, file will not be exported, but instead remapped to the given ``path``. + ---- .. _class_EditorExportPlugin_method_add_ios_bundle_file: - void **add_ios_bundle_file** **(** :ref:`String` path **)** +Adds an iOS bundle file from the given ``path`` to the exported project. + ---- .. _class_EditorExportPlugin_method_add_ios_cpp_code: - void **add_ios_cpp_code** **(** :ref:`String` code **)** +Adds a C++ code to the iOS export. The final code is created from the code appended by each active export plugin. + ---- .. _class_EditorExportPlugin_method_add_ios_embedded_framework: @@ -111,30 +126,40 @@ Adds a static library (\*.a) or dynamic library (\*.dylib, \*.framework) to Link - void **add_ios_linker_flags** **(** :ref:`String` flags **)** +Adds linker flags for the iOS export. + ---- .. _class_EditorExportPlugin_method_add_ios_plist_content: - void **add_ios_plist_content** **(** :ref:`String` plist_content **)** +Adds content for iOS Property List files. + ---- .. _class_EditorExportPlugin_method_add_ios_project_static_lib: - void **add_ios_project_static_lib** **(** :ref:`String` path **)** +Adds a static lib from the given ``path`` to the iOS project. + ---- .. _class_EditorExportPlugin_method_add_shared_object: - void **add_shared_object** **(** :ref:`String` path, :ref:`PoolStringArray` tags **)** +Adds a shared object with the given ``tags`` and destination ``path``. + ---- .. _class_EditorExportPlugin_method_skip: - void **skip** **(** **)** +To be called inside :ref:`_export_file`. Skips the current file, so it's not included in the export. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_editorfeatureprofile.rst b/classes/class_editorfeatureprofile.rst index 747a11b2e..6677c76b9 100644 --- a/classes/class_editorfeatureprofile.rst +++ b/classes/class_editorfeatureprofile.rst @@ -60,12 +60,12 @@ Enumerations .. _class_EditorFeatureProfile_constant_FEATURE_SCENE_TREE: -.. _class_EditorFeatureProfile_constant_FEATURE_IMPORT_DOCK: - .. _class_EditorFeatureProfile_constant_FEATURE_NODE_DOCK: .. _class_EditorFeatureProfile_constant_FEATURE_FILESYSTEM_DOCK: +.. _class_EditorFeatureProfile_constant_FEATURE_IMPORT_DOCK: + .. _class_EditorFeatureProfile_constant_FEATURE_MAX: enum **Feature**: @@ -78,11 +78,11 @@ enum **Feature**: - **FEATURE_SCENE_TREE** = **3** --- Scene tree editing. If this feature is disabled, the Scene tree dock will still be visible but will be read-only. -- **FEATURE_IMPORT_DOCK** = **4** --- The Import dock. If this feature is disabled, the Import dock won't be visible. +- **FEATURE_NODE_DOCK** = **4** --- The Node dock. If this feature is disabled, signals and groups won't be visible and modifiable from the editor. -- **FEATURE_NODE_DOCK** = **5** --- The Node dock. If this feature is disabled, signals and groups won't be visible and modifiable from the editor. +- **FEATURE_FILESYSTEM_DOCK** = **5** --- The FileSystem dock. If this feature is disabled, the FileSystem dock won't be visible. -- **FEATURE_FILESYSTEM_DOCK** = **6** --- The FileSystem dock. If this feature is disabled, the FileSystem dock won't be visible. +- **FEATURE_IMPORT_DOCK** = **6** --- The Import dock. If this feature is disabled, the Import dock won't be visible. - **FEATURE_MAX** = **7** --- Represents the size of the :ref:`Feature` enum. diff --git a/classes/class_editorfilesystem.rst b/classes/class_editorfilesystem.rst index fb540f94d..2314e3f14 100644 --- a/classes/class_editorfilesystem.rst +++ b/classes/class_editorfilesystem.rst @@ -58,7 +58,7 @@ Emitted if the filesystem changed. - **resources_reimported** **(** :ref:`PoolStringArray` resources **)** -Remitted if a resource is reimported. +Emitted if a resource is reimported. ---- diff --git a/classes/class_editorimportplugin.rst b/classes/class_editorimportplugin.rst index 2688ba86f..107da6c4b 100644 --- a/classes/class_editorimportplugin.rst +++ b/classes/class_editorimportplugin.rst @@ -31,7 +31,7 @@ Below is an example EditorImportPlugin that imports a :ref:`Mesh` fr return "my.special.plugin" func get_visible_name(): - return "Special Mesh Importer" + return "Special Mesh" func get_recognized_extensions(): return ["special", "spec"] @@ -60,8 +60,7 @@ Below is an example EditorImportPlugin that imports a :ref:`Mesh` fr # Fill the Mesh with data read in "file", left as an exercise to the reader var filename = save_path + "." + get_save_extension() - ResourceSaver.save(filename, mesh) - return OK + return ResourceSaver.save(filename, mesh) Tutorials --------- @@ -195,7 +194,7 @@ Gets the extension used to save this resource in the ``.import`` directory. - :ref:`String` **get_visible_name** **(** **)** |virtual| -Gets the name to display in the import window. +Gets the name to display in the import window. You should choose this name as a continuation to "Import as", e.g. "Import as Special Mesh". ---- diff --git a/classes/class_editorinspectorplugin.rst b/classes/class_editorinspectorplugin.rst index 9ac1570ee..df806c6b4 100644 --- a/classes/class_editorinspectorplugin.rst +++ b/classes/class_editorinspectorplugin.rst @@ -16,7 +16,7 @@ Plugin for adding custom property editors on inspector. Description ----------- -This plugins allows adding custom property editors to :ref:`EditorInspector`. +These plugins allow adding custom property editors to :ref:`EditorInspector`. Plugins are registered via :ref:`EditorPlugin.add_inspector_plugin`. @@ -26,7 +26,7 @@ If supported, the function :ref:`parse_begin` and :ref:`parse_property` are called for every category and property. They offer the ability to add custom controls to the inspector too. -Finally :ref:`parse_end` will be called. +Finally, :ref:`parse_end` will be called. On each of these calls, the "add" functions can be called. diff --git a/classes/class_editorinterface.rst b/classes/class_editorinterface.rst index d4336994f..b7dc79279 100644 --- a/classes/class_editorinterface.rst +++ b/classes/class_editorinterface.rst @@ -30,67 +30,69 @@ Properties Methods ------- -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`edit_resource` **(** :ref:`Resource` resource **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Control` | :ref:`get_base_control` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_current_path` **(** **)** |const| | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Node` | :ref:`get_edited_scene_root` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`EditorSettings` | :ref:`get_editor_settings` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Control` | :ref:`get_editor_viewport` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`FileSystemDock` | :ref:`get_file_system_dock` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`EditorInspector` | :ref:`get_inspector` **(** **)** |const| | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`get_open_scenes` **(** **)** |const| | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_playing_scene` **(** **)** |const| | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`EditorFileSystem` | :ref:`get_resource_filesystem` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`EditorResourcePreview` | :ref:`get_resource_previewer` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`ScriptEditor` | :ref:`get_script_editor` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_selected_path` **(** **)** |const| | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`EditorSelection` | :ref:`get_selection` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`inspect_object` **(** :ref:`Object` object, :ref:`String` for_property="" **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_playing_scene` **(** **)** |const| | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_plugin_enabled` **(** :ref:`String` plugin **)** |const| | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`make_mesh_previews` **(** :ref:`Array` meshes, :ref:`int` preview_size **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`open_scene_from_path` **(** :ref:`String` scene_filepath **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`play_current_scene` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`play_custom_scene` **(** :ref:`String` scene_filepath **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`play_main_scene` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`reload_scene_from_path` **(** :ref:`String` scene_filepath **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`save_scene` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`save_scene_as` **(** :ref:`String` path, :ref:`bool` with_preview=true **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`select_file` **(** :ref:`String` file **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_main_screen_editor` **(** :ref:`String` name **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_plugin_enabled` **(** :ref:`String` plugin, :ref:`bool` enabled **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`stop_playing_scene` **(** **)** | -+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`edit_resource` **(** :ref:`Resource` resource **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Control` | :ref:`get_base_control` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_current_path` **(** **)** |const| | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Node` | :ref:`get_edited_scene_root` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`get_editor_scale` **(** **)** |const| | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`EditorSettings` | :ref:`get_editor_settings` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Control` | :ref:`get_editor_viewport` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`FileSystemDock` | :ref:`get_file_system_dock` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`EditorInspector` | :ref:`get_inspector` **(** **)** |const| | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`get_open_scenes` **(** **)** |const| | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_playing_scene` **(** **)** |const| | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`EditorFileSystem` | :ref:`get_resource_filesystem` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`EditorResourcePreview` | :ref:`get_resource_previewer` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`ScriptEditor` | :ref:`get_script_editor` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_selected_path` **(** **)** |const| | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`EditorSelection` | :ref:`get_selection` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`inspect_object` **(** :ref:`Object` object, :ref:`String` for_property="", :ref:`bool` inspector_only=false **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`is_playing_scene` **(** **)** |const| | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`is_plugin_enabled` **(** :ref:`String` plugin **)** |const| | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`make_mesh_previews` **(** :ref:`Array` meshes, :ref:`int` preview_size **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`open_scene_from_path` **(** :ref:`String` scene_filepath **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`play_current_scene` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`play_custom_scene` **(** :ref:`String` scene_filepath **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`play_main_scene` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`reload_scene_from_path` **(** :ref:`String` scene_filepath **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`save_scene` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`save_scene_as` **(** :ref:`String` path, :ref:`bool` with_preview=true **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`select_file` **(** :ref:`String` file **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_main_screen_editor` **(** :ref:`String` name **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_plugin_enabled` **(** :ref:`String` plugin, :ref:`bool` enabled **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`stop_playing_scene` **(** **)** | ++-----------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Property Descriptions --------------------- @@ -142,6 +144,16 @@ Returns the edited (current) scene's root :ref:`Node`. ---- +.. _class_EditorInterface_method_get_editor_scale: + +- :ref:`float` **get_editor_scale** **(** **)** |const| + +Returns the actual scale of the editor UI (``1.0`` being 100% scale). This can be used to adjust position and dimensions of the UI added by plugins. + +**Note:** This value is set via the ``interface/editor/display_scale`` and ``interface/editor/custom_display_scale`` editor settings. Editor must be restarted for changes to be properly applied. + +---- + .. _class_EditorInterface_method_get_editor_settings: - :ref:`EditorSettings` **get_editor_settings** **(** **)** @@ -234,9 +246,9 @@ Returns the editor's :ref:`EditorSelection` instance. .. _class_EditorInterface_method_inspect_object: -- void **inspect_object** **(** :ref:`Object` object, :ref:`String` for_property="" **)** +- void **inspect_object** **(** :ref:`Object` object, :ref:`String` for_property="", :ref:`bool` inspector_only=false **)** -Shows the given property on the given ``object`` in the editor's Inspector dock. +Shows the given property on the given ``object`` in the editor's Inspector dock. If ``inspector_only`` is ``true``, plugins will not attempt to edit ``object``. ---- diff --git a/classes/class_editorplugin.rst b/classes/class_editorplugin.rst index 862b3cc23..738e9e915 100644 --- a/classes/class_editorplugin.rst +++ b/classes/class_editorplugin.rst @@ -69,6 +69,10 @@ Methods +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`forward_canvas_gui_input` **(** :ref:`InputEvent` event **)** |virtual| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`forward_spatial_draw_over_viewport` **(** :ref:`Control` overlay **)** |virtual| | ++-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`forward_spatial_force_draw_over_viewport` **(** :ref:`Control` overlay **)** |virtual| | ++-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`forward_spatial_gui_input` **(** :ref:`Camera` camera, :ref:`InputEvent` event **)** |virtual| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PoolStringArray` | :ref:`get_breakpoints` **(** **)** |virtual| | @@ -323,6 +327,8 @@ During run-time, this will be a simple object with a script so this function doe - void **add_export_plugin** **(** :ref:`EditorExportPlugin` plugin **)** +Registers a new export plugin. Export plugins are used when the project is being exported. See :ref:`EditorExportPlugin` for more information. + ---- .. _class_EditorPlugin_method_add_import_plugin: @@ -379,6 +385,10 @@ This is used, for example, in shader editors to let the plugin know that it must - :ref:`bool` **build** **(** **)** |virtual| +This method is called when the editor is about to run the project. The plugin can then perform required operations before the project runs. + +This method must return a boolean. If this method returns ``false``, the project will not run. The run is aborted immediately, so this also prevents all other plugins' :ref:`build` methods from running. + ---- .. _class_EditorPlugin_method_clear: @@ -417,12 +427,31 @@ Called by the engine when the user enables the ``EditorPlugin`` in the Plugin ta - void **forward_canvas_draw_over_viewport** **(** :ref:`Control` overlay **)** |virtual| +Called by the engine when the 2D editor's viewport is updated. Use the ``overlay`` :ref:`Control` for drawing. You can update the viewport manually by calling :ref:`update_overlays`. + +:: + + func forward_canvas_draw_over_viewport(overlay): + # Draw a circle at cursor position. + overlay.draw_circle(overlay.get_local_mouse_position(), 64) + + func forward_canvas_gui_input(event): + if event is InputEventMouseMotion: + # Redraw viewport when cursor is moved. + update_overlays() + return true + return false + ---- .. _class_EditorPlugin_method_forward_canvas_force_draw_over_viewport: - void **forward_canvas_force_draw_over_viewport** **(** :ref:`Control` overlay **)** |virtual| +This method is the same as :ref:`forward_canvas_draw_over_viewport`, except it draws on top of everything. Useful when you need an extra layer that shows over anything else. + +You need to enable calling of this method by using :ref:`set_force_draw_over_forwarding_enabled`. + ---- .. _class_EditorPlugin_method_forward_canvas_gui_input: @@ -451,6 +480,37 @@ Must ``return false`` in order to forward the :ref:`InputEvent ---- +.. _class_EditorPlugin_method_forward_spatial_draw_over_viewport: + +- void **forward_spatial_draw_over_viewport** **(** :ref:`Control` overlay **)** |virtual| + +Called by the engine when the 3D editor's viewport is updated. Use the ``overlay`` :ref:`Control` for drawing. You can update the viewport manually by calling :ref:`update_overlays`. + +:: + + func forward_spatial_draw_over_viewport(overlay): + # Draw a circle at cursor position. + overlay.draw_circle(overlay.get_local_mouse_position(), 64) + + func forward_spatial_gui_input(camera, event): + if event is InputEventMouseMotion: + # Redraw viewport when cursor is moved. + update_overlays() + return true + return false + +---- + +.. _class_EditorPlugin_method_forward_spatial_force_draw_over_viewport: + +- void **forward_spatial_force_draw_over_viewport** **(** :ref:`Control` overlay **)** |virtual| + +This method is the same as :ref:`forward_spatial_draw_over_viewport`, except it draws on top of everything. Useful when you need an extra layer that shows over anything else. + +You need to enable calling of this method by using :ref:`set_force_draw_over_forwarding_enabled`. + +---- + .. _class_EditorPlugin_method_forward_spatial_gui_input: - :ref:`bool` **forward_spatial_gui_input** **(** :ref:`Camera` camera, :ref:`InputEvent` event **)** |virtual| @@ -693,6 +753,8 @@ This method is called after the editor saves the project or when it's closed. It - void **set_force_draw_over_forwarding_enabled** **(** **)** +Enables calling of :ref:`forward_canvas_force_draw_over_viewport` for the 2D editor and :ref:`forward_spatial_force_draw_over_viewport` for the 3D editor when their viewports are updated. You need to call this method only once and it will work permanently for this plugin. + ---- .. _class_EditorPlugin_method_set_input_event_forwarding_always_enabled: @@ -723,7 +785,7 @@ Restore the plugin GUI layout saved by :ref:`get_window_layout` **update_overlays** **(** **)** |const| -Updates the overlays of the editor (2D/3D) viewport. +Updates the overlays of the 2D and 3D editor viewport. Causes methods :ref:`forward_canvas_draw_over_viewport`, :ref:`forward_canvas_force_draw_over_viewport`, :ref:`forward_spatial_draw_over_viewport` and :ref:`forward_spatial_force_draw_over_viewport` to be called. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_editorsceneimporter.rst b/classes/class_editorsceneimporter.rst index b8879073a..d422d1721 100644 --- a/classes/class_editorsceneimporter.rst +++ b/classes/class_editorsceneimporter.rst @@ -11,7 +11,7 @@ EditorSceneImporter **Inherits:** :ref:`Reference` **<** :ref:`Object` -**Inherited By:** :ref:`EditorSceneImporterAssimp` +**Inherited By:** :ref:`EditorSceneImporterFBX` Imports scenes from third-parties' 3D files. diff --git a/classes/class_editorsceneimporterassimp.rst b/classes/class_editorsceneimporterfbx.rst similarity index 77% rename from classes/class_editorsceneimporterassimp.rst rename to classes/class_editorsceneimporterfbx.rst index 3f90cf9b2..86d7f0aed 100644 --- a/classes/class_editorsceneimporterassimp.rst +++ b/classes/class_editorsceneimporterfbx.rst @@ -1,22 +1,22 @@ :github_url: hide .. Generated automatically by doc/tools/makerst.py in Godot's source tree. -.. DO NOT EDIT THIS FILE, but the EditorSceneImporterAssimp.xml source instead. +.. DO NOT EDIT THIS FILE, but the EditorSceneImporterFBX.xml source instead. .. The source is found in doc/classes or modules//doc_classes. -.. _class_EditorSceneImporterAssimp: +.. _class_EditorSceneImporterFBX: -EditorSceneImporterAssimp -========================= +EditorSceneImporterFBX +====================== **Inherits:** :ref:`EditorSceneImporter` **<** :ref:`Reference` **<** :ref:`Object` -FBX 3D asset importer based on `Assimp `_. +FBX 3D asset importer. Description ----------- -This is an FBX 3D asset importer based on `Assimp `_. It currently has many known limitations and works best with static meshes. Most animated meshes won't import correctly. +This is an FBX 3D asset importer with full support for most FBX features. If exporting a FBX scene from Autodesk Maya, use these FBX export settings: diff --git a/classes/class_editorspatialgizmoplugin.rst b/classes/class_editorspatialgizmoplugin.rst index cabf3f7c4..9a27bb833 100644 --- a/classes/class_editorspatialgizmoplugin.rst +++ b/classes/class_editorspatialgizmoplugin.rst @@ -45,11 +45,11 @@ Methods +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get_handle_value` **(** :ref:`EditorSpatialGizmo` gizmo, :ref:`int` index **)** |virtual| | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`SpatialMaterial` | :ref:`get_material` **(** :ref:`String` name, :ref:`EditorSpatialGizmo` gizmo **)** | +| :ref:`SpatialMaterial` | :ref:`get_material` **(** :ref:`String` name, :ref:`EditorSpatialGizmo` gizmo=null **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_name` **(** **)** |virtual| | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_priority` **(** **)** |virtual| | +| :ref:`int` | :ref:`get_priority` **(** **)** |virtual| | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_gizmo` **(** :ref:`Spatial` spatial **)** |virtual| | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -139,7 +139,7 @@ Gets actual value of a handle from gizmo. Called for this plugin's active gizmos .. _class_EditorSpatialGizmoPlugin_method_get_material: -- :ref:`SpatialMaterial` **get_material** **(** :ref:`String` name, :ref:`EditorSpatialGizmo` gizmo **)** +- :ref:`SpatialMaterial` **get_material** **(** :ref:`String` name, :ref:`EditorSpatialGizmo` gizmo=null **)** Gets material from the internal list of materials. If an :ref:`EditorSpatialGizmo` is provided, it will try to get the corresponding variant (selected and/or editable). @@ -155,7 +155,7 @@ Override this method to provide the name that will appear in the gizmo visibilit .. _class_EditorSpatialGizmoPlugin_method_get_priority: -- :ref:`String` **get_priority** **(** **)** |virtual| +- :ref:`int` **get_priority** **(** **)** |virtual| Override this method to set the gizmo's priority. Higher values correspond to higher priority. If a gizmo with higher priority conflicts with another gizmo, only the gizmo with higher priority will be used. @@ -183,7 +183,7 @@ Gets whether a handle is highlighted or not. Called for this plugin's active giz - :ref:`bool` **is_selectable_when_hidden** **(** **)** |virtual| -Override this method to define whether Spatial with this gizmo should be selecteble even when the gizmo is hidden. +Override this method to define whether a Spatial with this gizmo should be selectable even when the gizmo is hidden. ---- diff --git a/classes/class_editorvcsinterface.rst b/classes/class_editorvcsinterface.rst index 4b7d80870..5292ab09c 100644 --- a/classes/class_editorvcsinterface.rst +++ b/classes/class_editorvcsinterface.rst @@ -82,7 +82,7 @@ Each :ref:`Dictionary` object has the line diff contents under - :ref:`Dictionary` **get_modified_files_data** **(** **)** -Returns a :ref:`Dictionary` containing the path of the detected file change mapped to an integer signifying what kind of a change the corresponding file has experienced. +Returns a :ref:`Dictionary` containing the path of the detected file change mapped to an integer signifying what kind of change the corresponding file has experienced. The following integer values are being used to signify that the detected file is: diff --git a/classes/class_engine.rst b/classes/class_engine.rst index 8cf6822a2..d0f6e4bc8 100644 --- a/classes/class_engine.rst +++ b/classes/class_engine.rst @@ -115,7 +115,7 @@ The number of fixed iterations per second. This controls how often physics simul | *Getter* | get_physics_jitter_fix() | +-----------+-------------------------------+ -Controls how much physics ticks are synchronized with real time. For 0 or less, the ticks are synchronized. Such values are recommended for network games, where clock synchronization matters. Higher values cause higher deviation of in-game clock and real clock, but allows to smooth out framerate jitters. The default value of 0.5 should be fine for most; values above 2 could cause the game to react to dropped frames with a noticeable delay and are not recommended. +Controls how much physics ticks are synchronized with real time. For 0 or less, the ticks are synchronized. Such values are recommended for network games, where clock synchronization matters. Higher values cause higher deviation of in-game clock and real clock, but allows smoothing out framerate jitters. The default value of 0.5 should be fine for most; values above 2 could cause the game to react to dropped frames with a noticeable delay and are not recommended. ---- diff --git a/classes/class_environment.rst b/classes/class_environment.rst index 5e8bf24ce..4840740b7 100644 --- a/classes/class_environment.rst +++ b/classes/class_environment.rst @@ -35,6 +35,12 @@ Tutorials - :doc:`../tutorials/3d/high_dynamic_range` +- `https://godotengine.org/asset-library/asset/123 `_ + +- `https://godotengine.org/asset-library/asset/110 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_file.rst b/classes/class_file.rst index 24edd7709..4f2bb629b 100644 --- a/classes/class_file.rst +++ b/classes/class_file.rst @@ -35,13 +35,19 @@ Here's a sample on how to write and read from a file: file.close() return content -In the example above, the file will be saved in the user data folder as specified in the `Data paths `_ documentation. +In the example above, the file will be saved in the user data folder as specified in the `Data paths `_ documentation. + +**Note:** To access project resources once exported, it is recommended to use :ref:`ResourceLoader` instead of the ``File`` API, as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package. + +**Note:** Files are automatically closed only if the process exits "normally" (such as by clicking the window manager's close button or pressing **Alt + F4**). If you stop the project execution by pressing **F8** while the project is running, the file won't be closed as the game process will be killed. You can work around this by calling :ref:`flush` at regular intervals. Tutorials --------- - :doc:`../getting_started/step_by_step/filesystem` +- `https://godotengine.org/asset-library/asset/676 `_ + Properties ---------- @@ -59,6 +65,8 @@ Methods +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`file_exists` **(** :ref:`String` path **)** |const| | +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`flush` **(** **)** | ++-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_16` **(** **)** |const| | +-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_32` **(** **)** |const| | @@ -202,9 +210,11 @@ Property Descriptions | *Getter* | get_endian_swap() | +-----------+------------------------+ -If ``true``, the file's endianness is swapped. Use this if you're dealing with files written on big-endian machines. +If ``true``, the file is read with big-endian `endianness `_. If ``false``, the file is read with little-endian endianness. If in doubt, leave this to ``false`` as most files are written with little-endian endianness. -**Note:** This is about the file format, not CPU type. This is always reset to ``false`` whenever you open the file. +**Note:** :ref:`endian_swap` is only about the file format, not the CPU type. The CPU endianness doesn't affect the default endianness for files written. + +**Note:** This is always reset to ``false`` whenever you open the file. Therefore, you must set :ref:`endian_swap` *after* opening the file, not before. Method Descriptions ------------------- @@ -213,7 +223,7 @@ Method Descriptions - void **close** **(** **)** -Closes the currently opened file. +Closes the currently opened file and prevents subsequent read/write operations. Use :ref:`flush` to persist the data to disk without closing the file. ---- @@ -233,7 +243,17 @@ Returns ``true`` if the file cursor has read past the end of the file. Returns ``true`` if the file exists in the given path. -**Note:** Many resources types are imported (e.g. textures or sound files), and that their source asset will not be included in the exported game, as only the imported version is used (in the ``res://.import`` folder). To check for the existence of such resources while taking into account the remapping to their imported location, use :ref:`ResourceLoader.exists`. Typically, using ``File.file_exists`` on an imported resource would work while you are developing in the editor (the source asset is present in ``res://``, but fail when exported). +**Note:** Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. See :ref:`ResourceLoader.exists` for an alternative approach that takes resource remapping into account. + +---- + +.. _class_File_method_flush: + +- void **flush** **(** **)** + +Writes the file's buffer to disk. Flushing is automatically performed when the file is closed. This means you don't need to call :ref:`flush` manually before closing a file using :ref:`close`. Still, calling :ref:`flush` can be used to ensure the data is safe even if the project crashes instead of being closed gracefully. + +**Note:** Only call :ref:`flush` when you actually need it. Otherwise, it will decrease performance due to constant disk writes. ---- @@ -578,9 +598,7 @@ Stores a floating-point number as 32 bits in the file. - void **store_line** **(** :ref:`String` line **)** -Stores the given :ref:`String` as a line in the file. - -Text will be encoded as UTF-8. +Appends ``line`` to the file followed by a line return character (``\n``), encoding the text as UTF-8. ---- @@ -606,9 +624,7 @@ Stores a floating-point number in the file. - void **store_string** **(** :ref:`String` string **)** -Stores the given :ref:`String` in the file. - -Text will be encoded as UTF-8. +Appends ``string`` to the file without a line return, encoding the text as UTF-8. ---- diff --git a/classes/class_font.rst b/classes/class_font.rst index 730a983ce..6058d020a 100644 --- a/classes/class_font.rst +++ b/classes/class_font.rst @@ -84,7 +84,7 @@ Returns the font ascent (number of pixels above the baseline). - :ref:`Vector2` **get_char_size** **(** :ref:`int` char, :ref:`int` next=0 **)** |const| -Returns the size of a character, optionally taking kerning into account if the next character is provided. +Returns the size of a character, optionally taking kerning into account if the next character is provided. Note that the height returned is the font height (see :ref:`get_height`) and has no relation to the glyph height. ---- @@ -108,7 +108,7 @@ Returns the total font height (ascent plus descent) in pixels. - :ref:`Vector2` **get_string_size** **(** :ref:`String` string **)** |const| -Returns the size of a string, taking kerning and advance into account. +Returns the size of a string, taking kerning and advance into account. Note that the height returned is the font height (see :ref:`get_height`) and has no relation to the string. ---- diff --git a/classes/class_funcref.rst b/classes/class_funcref.rst index 70d3601b4..e3e248455 100644 --- a/classes/class_funcref.rst +++ b/classes/class_funcref.rst @@ -20,6 +20,13 @@ In GDScript, functions are not *first-class objects*. This means it is impossibl However, by creating a ``FuncRef`` using the :ref:`@GDScript.funcref` function, a reference to a function in a given object can be created, passed around and called. +Properties +---------- + ++-----------------------------+--------------------------------------------------+--------+ +| :ref:`String` | :ref:`function` | ``""`` | ++-----------------------------+--------------------------------------------------+--------+ + Methods ------- @@ -30,11 +37,26 @@ Methods +-------------------------------+---------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_valid` **(** **)** |const| | +-------------------------------+---------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_function` **(** :ref:`String` name **)** | -+-------------------------------+---------------------------------------------------------------------------------------------------------+ | void | :ref:`set_instance` **(** :ref:`Object` instance **)** | +-------------------------------+---------------------------------------------------------------------------------------------------------+ +Property Descriptions +--------------------- + +.. _class_FuncRef_property_function: + +- :ref:`String` **function** + ++-----------+---------------------+ +| *Default* | ``""`` | ++-----------+---------------------+ +| *Setter* | set_function(value) | ++-----------+---------------------+ +| *Getter* | get_function() | ++-----------+---------------------+ + +The name of the referenced function. + Method Descriptions ------------------- @@ -42,7 +64,7 @@ Method Descriptions - :ref:`Variant` **call_func** **(** ... **)** |vararg| -Calls the referenced function previously set by :ref:`set_function` or :ref:`@GDScript.funcref`. +Calls the referenced function previously set in :ref:`function` or :ref:`@GDScript.funcref`. ---- @@ -50,7 +72,7 @@ Calls the referenced function previously set by :ref:`set_function` **call_funcv** **(** :ref:`Array` arg_array **)** -Calls the referenced function previously set by :ref:`set_function` or :ref:`@GDScript.funcref`. Contrarily to :ref:`call_func`, this method does not support a variable number of arguments but expects all parameters to be passed via a single :ref:`Array`. +Calls the referenced function previously set in :ref:`function` or :ref:`@GDScript.funcref`. Contrarily to :ref:`call_func`, this method does not support a variable number of arguments but expects all parameters to be passed via a single :ref:`Array`. ---- @@ -62,14 +84,6 @@ Returns whether the object still exists and has the function assigned. ---- -.. _class_FuncRef_method_set_function: - -- void **set_function** **(** :ref:`String` name **)** - -The name of the referenced function to call on the object, without parentheses or any parameters. - ----- - .. _class_FuncRef_method_set_instance: - void **set_instance** **(** :ref:`Object` instance **)** diff --git a/classes/class_generic6dofjoint.rst b/classes/class_generic6dofjoint.rst index 22b66de47..ac17b2c5d 100644 --- a/classes/class_generic6dofjoint.rst +++ b/classes/class_generic6dofjoint.rst @@ -190,8 +190,6 @@ Properties +---------------------------+---------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`float` | :ref:`linear_spring_z/stiffness` | ``0.01`` | +---------------------------+---------------------------------------------------------------------------------------------------------------+-----------+ -| :ref:`int` | :ref:`precision` | ``1`` | -+---------------------------+---------------------------------------------------------------------------------------------------------------+-----------+ Methods ------- @@ -1630,20 +1628,6 @@ The speed that the linear motor will attempt to reach on the Z axis. | *Getter* | get_param_z() | +-----------+--------------------+ ----- - -.. _class_Generic6DOFJoint_property_precision: - -- :ref:`int` **precision** - -+-----------+----------------------+ -| *Default* | ``1`` | -+-----------+----------------------+ -| *Setter* | set_precision(value) | -+-----------+----------------------+ -| *Getter* | get_precision() | -+-----------+----------------------+ - Method Descriptions ------------------- diff --git a/classes/class_geometry.rst b/classes/class_geometry.rst index a9cc6d44c..02ddfb8dc 100644 --- a/classes/class_geometry.rst +++ b/classes/class_geometry.rst @@ -201,7 +201,7 @@ Clips the polygon defined by the points in ``points`` against the ``plane`` and Clips ``polygon_a`` against ``polygon_b`` and returns an array of clipped polygons. This performs :ref:`OPERATION_DIFFERENCE` between polygons. Returns an empty array if ``polygon_b`` completely overlaps ``polygon_a``. -If ``polygon_b`` is enclosed by ``polygon_a``, returns an outer polygon (boundary) and inner polygon (hole) which could be distiguished by calling :ref:`is_polygon_clockwise`. +If ``polygon_b`` is enclosed by ``polygon_a``, returns an outer polygon (boundary) and inner polygon (hole) which could be distinguished by calling :ref:`is_polygon_clockwise`. ---- @@ -227,7 +227,7 @@ Given an array of :ref:`Vector2`\ s, returns the convex hull as a Mutually excludes common area defined by intersection of ``polygon_a`` and ``polygon_b`` (see :ref:`intersect_polygons_2d`) and returns an array of excluded polygons. This performs :ref:`OPERATION_XOR` between polygons. In other words, returns all but common area between polygons. -The operation may result in an outer polygon (boundary) and inner polygon (hole) produced which could be distiguished by calling :ref:`is_polygon_clockwise`. +The operation may result in an outer polygon (boundary) and inner polygon (hole) produced which could be distinguished by calling :ref:`is_polygon_clockwise`. ---- @@ -275,7 +275,7 @@ Given the two 3D segments (``p1``, ``p2``) and (``q1``, ``q2``), finds those two - :ref:`PoolVector2Array` **get_closest_points_between_segments_2d** **(** :ref:`Vector2` p1, :ref:`Vector2` q1, :ref:`Vector2` p2, :ref:`Vector2` q2 **)** -Given the two 2D segments (``p1``, ``p2``) and (``q1``, ``q2``), finds those two points on the two segments that are closest to each other. Returns a :ref:`PoolVector2Array` that contains this point on (``p1``, ``p2``) as well the accompanying point on (``q1``, ``q2``). +Given the two 2D segments (``p1``, ``q1``) and (``p2``, ``q2``), finds those two points on the two segments that are closest to each other. Returns a :ref:`PoolVector2Array` that contains this point on (``p1``, ``q1``) as well the accompanying point on (``p2``, ``q2``). ---- diff --git a/classes/class_geometryinstance.rst b/classes/class_geometryinstance.rst index 740b3bf62..9882d2231 100644 --- a/classes/class_geometryinstance.rst +++ b/classes/class_geometryinstance.rst @@ -28,6 +28,10 @@ Properties +-------------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ | :ref:`float` | :ref:`extra_cull_margin` | ``0.0`` | +-------------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ +| :ref:`bool` | :ref:`generate_lightmap` | ``true`` | ++-------------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ +| :ref:`LightmapScale` | :ref:`lightmap_scale` | ``0`` | ++-------------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ | :ref:`float` | :ref:`lod_max_distance` | ``0.0`` | +-------------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ | :ref:`float` | :ref:`lod_max_hysteresis` | ``0.0`` | @@ -55,6 +59,32 @@ Methods Enumerations ------------ +.. _enum_GeometryInstance_LightmapScale: + +.. _class_GeometryInstance_constant_LIGHTMAP_SCALE_1X: + +.. _class_GeometryInstance_constant_LIGHTMAP_SCALE_2X: + +.. _class_GeometryInstance_constant_LIGHTMAP_SCALE_4X: + +.. _class_GeometryInstance_constant_LIGHTMAP_SCALE_8X: + +.. _class_GeometryInstance_constant_LIGHTMAP_SCALE_MAX: + +enum **LightmapScale**: + +- **LIGHTMAP_SCALE_1X** = **0** --- The generated lightmap texture will have the original size. + +- **LIGHTMAP_SCALE_2X** = **1** --- The generated lightmap texture will be twice as large, on each axis. + +- **LIGHTMAP_SCALE_4X** = **2** --- The generated lightmap texture will be 4 times as large, on each axis. + +- **LIGHTMAP_SCALE_8X** = **3** --- The generated lightmap texture will be 8 times as large, on each axis. + +- **LIGHTMAP_SCALE_MAX** = **4** + +---- + .. _enum_GeometryInstance_ShadowCastingSetting: .. _class_GeometryInstance_constant_SHADOW_CASTING_SETTING_OFF: @@ -134,6 +164,38 @@ The extra distance added to the GeometryInstance's bounding box (:ref:`AABB` **generate_lightmap** + ++-----------+------------------------------+ +| *Default* | ``true`` | ++-----------+------------------------------+ +| *Setter* | set_generate_lightmap(value) | ++-----------+------------------------------+ +| *Getter* | get_generate_lightmap() | ++-----------+------------------------------+ + +When disabled, the mesh will be taken into account when computing indirect lighting, but the resulting lightmap will not be saved. Useful for emissive only materials or shadow casters. + +---- + +.. _class_GeometryInstance_property_lightmap_scale: + +- :ref:`LightmapScale` **lightmap_scale** + ++-----------+---------------------------+ +| *Default* | ``0`` | ++-----------+---------------------------+ +| *Setter* | set_lightmap_scale(value) | ++-----------+---------------------------+ +| *Getter* | get_lightmap_scale() | ++-----------+---------------------------+ + +Scale factor for the generated baked lightmap. Useful for adding detail to certain mesh instances. + +---- + .. _class_GeometryInstance_property_lod_max_distance: - :ref:`float` **lod_max_distance** diff --git a/classes/class_giprobe.rst b/classes/class_giprobe.rst index 79b0333f6..f3acbb089 100644 --- a/classes/class_giprobe.rst +++ b/classes/class_giprobe.rst @@ -20,11 +20,17 @@ Description Having ``GIProbe``\ s in a scene can be expensive, the quality of the probe can be turned down in exchange for better performance in the :ref:`ProjectSettings` using :ref:`ProjectSettings.rendering/quality/voxel_cone_tracing/high_quality`. +**Note:** Meshes should have sufficiently thick walls to avoid light leaks (avoid one-sided walls). For interior levels, enclose your level geometry in a sufficiently large box and bridge the loops to close the mesh. + +**Note:** Due to a renderer limitation, emissive :ref:`ShaderMaterial`\ s cannot emit light when used in a ``GIProbe``. Only emissive :ref:`SpatialMaterial`\ s can emit light in a ``GIProbe``. + Tutorials --------- - :doc:`../tutorials/3d/gi_probes` +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_giprobedata.rst b/classes/class_giprobedata.rst index 34f0f981a..56574705e 100644 --- a/classes/class_giprobedata.rst +++ b/classes/class_giprobedata.rst @@ -13,6 +13,11 @@ GIProbeData +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_gradient.rst b/classes/class_gradient.rst index f38f95916..bbaccf570 100644 --- a/classes/class_gradient.rst +++ b/classes/class_gradient.rst @@ -33,15 +33,15 @@ Methods +---------------------------+---------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_point` **(** :ref:`float` offset, :ref:`Color` color **)** | +---------------------------+---------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`get_color` **(** :ref:`int` point **)** |const| | +| :ref:`Color` | :ref:`get_color` **(** :ref:`int` point **)** | +---------------------------+---------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_offset` **(** :ref:`int` point **)** |const| | +| :ref:`float` | :ref:`get_offset` **(** :ref:`int` point **)** | +---------------------------+---------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_point_count` **(** **)** |const| | +---------------------------+---------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Color` | :ref:`interpolate` **(** :ref:`float` offset **)** | +---------------------------+---------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_point` **(** :ref:`int` offset **)** | +| void | :ref:`remove_point` **(** :ref:`int` point **)** | +---------------------------+---------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_color` **(** :ref:`int` point, :ref:`Color` color **)** | +---------------------------+---------------------------------------------------------------------------------------------------------------------------------+ @@ -94,7 +94,7 @@ Adds the specified color to the end of the ramp, with the specified offset. .. _class_Gradient_method_get_color: -- :ref:`Color` **get_color** **(** :ref:`int` point **)** |const| +- :ref:`Color` **get_color** **(** :ref:`int` point **)** Returns the color of the ramp color at index ``point``. @@ -102,7 +102,7 @@ Returns the color of the ramp color at index ``point``. .. _class_Gradient_method_get_offset: -- :ref:`float` **get_offset** **(** :ref:`int` point **)** |const| +- :ref:`float` **get_offset** **(** :ref:`int` point **)** Returns the offset of the ramp color at index ``point``. @@ -126,9 +126,9 @@ Returns the interpolated color specified by ``offset``. .. _class_Gradient_method_remove_point: -- void **remove_point** **(** :ref:`int` offset **)** +- void **remove_point** **(** :ref:`int` point **)** -Removes the color at the index ``offset``. +Removes the color at the index ``point``. ---- diff --git a/classes/class_graphedit.rst b/classes/class_graphedit.rst index 4475bfb28..5a70b1c6e 100644 --- a/classes/class_graphedit.rst +++ b/classes/class_graphedit.rst @@ -26,6 +26,12 @@ Properties +------------------------------------------+----------------------------------------------------------------------+------------------------------+ | :ref:`FocusMode` | focus_mode | ``2`` *(parent override)* | +------------------------------------------+----------------------------------------------------------------------+------------------------------+ +| :ref:`bool` | :ref:`minimap_enabled` | ``true`` | ++------------------------------------------+----------------------------------------------------------------------+------------------------------+ +| :ref:`float` | :ref:`minimap_opacity` | ``0.65`` | ++------------------------------------------+----------------------------------------------------------------------+------------------------------+ +| :ref:`Vector2` | :ref:`minimap_size` | ``Vector2( 240, 160 )`` | ++------------------------------------------+----------------------------------------------------------------------+------------------------------+ | :ref:`bool` | rect_clip_content | ``true`` *(parent override)* | +------------------------------------------+----------------------------------------------------------------------+------------------------------+ | :ref:`bool` | :ref:`right_disconnects` | ``false`` | @@ -90,6 +96,8 @@ Theme Properties +---------------------------------+-------------------------------+------------------------+ | :ref:`Color` | grid_minor | Color( 1, 1, 1, 0.05 ) | +---------------------------------+-------------------------------+------------------------+ +| :ref:`Texture` | minimap | | ++---------------------------------+-------------------------------+------------------------+ | :ref:`Texture` | minus | | +---------------------------------+-------------------------------+------------------------+ | :ref:`Texture` | more | | @@ -221,6 +229,54 @@ Emitted when the scroll offset is changed by the user. It will not be emitted wh Property Descriptions --------------------- +.. _class_GraphEdit_property_minimap_enabled: + +- :ref:`bool` **minimap_enabled** + ++-----------+----------------------------+ +| *Default* | ``true`` | ++-----------+----------------------------+ +| *Setter* | set_minimap_enabled(value) | ++-----------+----------------------------+ +| *Getter* | is_minimap_enabled() | ++-----------+----------------------------+ + +If ``true``, the minimap is visible. + +---- + +.. _class_GraphEdit_property_minimap_opacity: + +- :ref:`float` **minimap_opacity** + ++-----------+----------------------------+ +| *Default* | ``0.65`` | ++-----------+----------------------------+ +| *Setter* | set_minimap_opacity(value) | ++-----------+----------------------------+ +| *Getter* | get_minimap_opacity() | ++-----------+----------------------------+ + +The opacity of the minimap rectangle. + +---- + +.. _class_GraphEdit_property_minimap_size: + +- :ref:`Vector2` **minimap_size** + ++-----------+-------------------------+ +| *Default* | ``Vector2( 240, 160 )`` | ++-----------+-------------------------+ +| *Setter* | set_minimap_size(value) | ++-----------+-------------------------+ +| *Getter* | get_minimap_size() | ++-----------+-------------------------+ + +The size of the minimap rectangle. The map itself is based on the size of the grid area and is scaled to fit this rectangle. + +---- + .. _class_GraphEdit_property_right_disconnects: - :ref:`bool` **right_disconnects** @@ -364,7 +420,7 @@ Returns an Array containing the list of connections. A connection consists in a Gets the :ref:`HBoxContainer` that contains the zooming and grid snap controls in the top left of the graph. -Warning: The intended usage of this function is to allow you to reposition or add your own custom controls to the container. This is an internal control and as such should not be freed. If you wish to hide this or any of it's children use their :ref:`CanvasItem.visible` property instead. +Warning: The intended usage of this function is to allow you to reposition or add your own custom controls to the container. This is an internal control and as such should not be freed. If you wish to hide this or any of its children, use their :ref:`CanvasItem.visible` property instead. ---- diff --git a/classes/class_graphnode.rst b/classes/class_graphnode.rst index 80e23c941..77febff61 100644 --- a/classes/class_graphnode.rst +++ b/classes/class_graphnode.rst @@ -20,7 +20,7 @@ A GraphNode is a container. Each GraphNode can have several input and output slo After adding at least one child to GraphNode new sections will be automatically created in the Inspector called 'Slot'. When 'Slot' is expanded you will see list with index number for each slot. You can click on each of them to expand further. -In the Inspector you can enable (show) or disable (hide) slots. By default all slots are disabled so you may not see any slots on your GraphNode initially. You can assign a type to each slot. Only slots of the same type will be able to connect to each other. You can also assign colors to slots. A tuple of input and output slots is defined for each GUI element included in the GraphNode. Input connections are on the left and output connections are on the right side of GraphNode. Only enabled slots are counted as connections. +In the Inspector you can enable (show) or disable (hide) slots. By default, all slots are disabled so you may not see any slots on your GraphNode initially. You can assign a type to each slot. Only slots of the same type will be able to connect to each other. You can also assign colors to slots. A tuple of input and output slots is defined for each GUI element included in the GraphNode. Input connections are on the left and output connections are on the right side of GraphNode. Only enabled slots are counted as connections. Properties ---------- @@ -164,6 +164,14 @@ Emitted when the GraphNode is requested to be displayed over other ones. Happens Emitted when the GraphNode is requested to be resized. Happens on dragging the resizer handle (see :ref:`resizable`). +---- + +.. _class_GraphNode_signal_slot_updated: + +- **slot_updated** **(** :ref:`int` idx **)** + +Emitted when any GraphNode's slot is updated. + Enumerations ------------ diff --git a/classes/class_gridcontainer.rst b/classes/class_gridcontainer.rst index a4ef9ad22..f045ee5aa 100644 --- a/classes/class_gridcontainer.rst +++ b/classes/class_gridcontainer.rst @@ -22,6 +22,11 @@ Notice that grid layout will preserve the columns and rows for every size of the **Note:** GridContainer only works with child nodes inheriting from Control. It won't rearrange child nodes inheriting from Node2D. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/677 `_ + Properties ---------- diff --git a/classes/class_gridmap.rst b/classes/class_gridmap.rst index 4669d3e03..91a159954 100644 --- a/classes/class_gridmap.rst +++ b/classes/class_gridmap.rst @@ -24,33 +24,41 @@ A GridMap contains a collection of cells. Each grid cell refers to a tile in the Internally, a GridMap is split into a sparse collection of octants for efficient rendering and physics processing. Every octant has the same dimensions and can contain several cells. +**Note:** GridMap doesn't extend :ref:`VisualInstance` and therefore can't be hidden or cull masked based on :ref:`VisualInstance.layers`. If you make a light not affect the first layer, the whole GridMap won't be lit by the light in question. + Tutorials --------- - :doc:`../tutorials/3d/using_gridmaps` +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/126 `_ + Properties ---------- -+---------------------------------------+------------------------------------------------------------------+------------------------+ -| :ref:`bool` | :ref:`cell_center_x` | ``true`` | -+---------------------------------------+------------------------------------------------------------------+------------------------+ -| :ref:`bool` | :ref:`cell_center_y` | ``true`` | -+---------------------------------------+------------------------------------------------------------------+------------------------+ -| :ref:`bool` | :ref:`cell_center_z` | ``true`` | -+---------------------------------------+------------------------------------------------------------------+------------------------+ -| :ref:`int` | :ref:`cell_octant_size` | ``8`` | -+---------------------------------------+------------------------------------------------------------------+------------------------+ -| :ref:`float` | :ref:`cell_scale` | ``1.0`` | -+---------------------------------------+------------------------------------------------------------------+------------------------+ -| :ref:`Vector3` | :ref:`cell_size` | ``Vector3( 2, 2, 2 )`` | -+---------------------------------------+------------------------------------------------------------------+------------------------+ -| :ref:`int` | :ref:`collision_layer` | ``1`` | -+---------------------------------------+------------------------------------------------------------------+------------------------+ -| :ref:`int` | :ref:`collision_mask` | ``1`` | -+---------------------------------------+------------------------------------------------------------------+------------------------+ -| :ref:`MeshLibrary` | :ref:`mesh_library` | | -+---------------------------------------+------------------------------------------------------------------+------------------------+ ++---------------------------------------+----------------------------------------------------------------------+------------------------+ +| :ref:`bool` | :ref:`cell_center_x` | ``true`` | ++---------------------------------------+----------------------------------------------------------------------+------------------------+ +| :ref:`bool` | :ref:`cell_center_y` | ``true`` | ++---------------------------------------+----------------------------------------------------------------------+------------------------+ +| :ref:`bool` | :ref:`cell_center_z` | ``true`` | ++---------------------------------------+----------------------------------------------------------------------+------------------------+ +| :ref:`int` | :ref:`cell_octant_size` | ``8`` | ++---------------------------------------+----------------------------------------------------------------------+------------------------+ +| :ref:`float` | :ref:`cell_scale` | ``1.0`` | ++---------------------------------------+----------------------------------------------------------------------+------------------------+ +| :ref:`Vector3` | :ref:`cell_size` | ``Vector3( 2, 2, 2 )`` | ++---------------------------------------+----------------------------------------------------------------------+------------------------+ +| :ref:`int` | :ref:`collision_layer` | ``1`` | ++---------------------------------------+----------------------------------------------------------------------+------------------------+ +| :ref:`int` | :ref:`collision_mask` | ``1`` | ++---------------------------------------+----------------------------------------------------------------------+------------------------+ +| :ref:`MeshLibrary` | :ref:`mesh_library` | | ++---------------------------------------+----------------------------------------------------------------------+------------------------+ +| :ref:`bool` | :ref:`use_in_baked_light` | ``false`` | ++---------------------------------------+----------------------------------------------------------------------+------------------------+ Methods ------- @@ -242,7 +250,7 @@ GridMaps act as static bodies, meaning they aren't affected by gravity or other | *Getter* | get_collision_mask() | +-----------+---------------------------+ -The physics layers this GridMap detects collisions in. See `Collision layers and masks `_ in the documentation for more information. +The physics layers this GridMap detects collisions in. See `Collision layers and masks `_ in the documentation for more information. ---- @@ -258,6 +266,22 @@ The physics layers this GridMap detects collisions in. See `Collision layers and The assigned :ref:`MeshLibrary`. +---- + +.. _class_GridMap_property_use_in_baked_light: + +- :ref:`bool` **use_in_baked_light** + ++-----------+-------------------------------+ +| *Default* | ``false`` | ++-----------+-------------------------------+ +| *Setter* | set_use_in_baked_light(value) | ++-----------+-------------------------------+ +| *Getter* | get_use_in_baked_light() | ++-----------+-------------------------------+ + +Controls whether this GridMap will be baked in a :ref:`BakedLightmap` or not. + Method Descriptions ------------------- @@ -285,6 +309,8 @@ Clear all cells. - :ref:`Array` **get_bake_meshes** **(** **)** +Returns an array of :ref:`ArrayMesh`\ es and :ref:`Transform` references of all bake meshes that exist within the current GridMap. + ---- .. _class_GridMap_method_get_cell_item: diff --git a/classes/class_hingejoint.rst b/classes/class_hingejoint.rst index 557939438..1790ed556 100644 --- a/classes/class_hingejoint.rst +++ b/classes/class_hingejoint.rst @@ -11,12 +11,12 @@ HingeJoint **Inherits:** :ref:`Joint` **<** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` -A hinge between two 3D bodies. +A hinge between two 3D PhysicsBodies. Description ----------- -A HingeJoint normally uses the Z axis of body A as the hinge axis, another axis can be specified when adding it manually though. +A HingeJoint normally uses the Z axis of body A as the hinge axis, another axis can be specified when adding it manually though. See also :ref:`Generic6DOFJoint`. Properties ---------- diff --git a/classes/class_httpclient.rst b/classes/class_httpclient.rst index dca5dfd89..7c437762e 100644 --- a/classes/class_httpclient.rst +++ b/classes/class_httpclient.rst @@ -16,7 +16,7 @@ Low-level hyper-text transfer protocol client. Description ----------- -Hyper-text transfer protocol client (sometimes called "User Agent"). Used to make HTTP requests to download web content, upload files and other data or to communicate with various services, among other use cases. **See the :ref:`HTTPRequest` node for an higher-level alternative.** +Hyper-text transfer protocol client (sometimes called "User Agent"). Used to make HTTP requests to download web content, upload files and other data or to communicate with various services, among other use cases. **See the :ref:`HTTPRequest` node for a higher-level alternative.** **Note:** This client only needs to connect to a host once (see :ref:`connect_to_host`) to send multiple requests. Because of this, methods that take URLs usually take just the part after the host instead of the full URL, as the client is already connected to a host. See :ref:`request` for a full example and to get started. @@ -26,6 +26,8 @@ For more information on HTTP, see https://developer.mozilla.org/en-US/docs/Web/H **Note:** When performing HTTP requests from a project exported to HTML5, keep in mind the remote server may not allow requests from foreign origins due to `CORS `_. If you host the server in question, you should modify its backend to allow requests from foreign origins by adding the ``Access-Control-Allow-Origin: *`` HTTP header. +**Note:** SSL/TLS support is currently limited to TLS 1.0, TLS 1.1, and TLS 1.2. Attempting to connect to a TLS 1.3-only server will return an error. + Tutorials --------- @@ -41,7 +43,7 @@ Properties +-------------------------------------+-------------------------------------------------------------------------------+-----------+ | :ref:`StreamPeer` | :ref:`connection` | | +-------------------------------------+-------------------------------------------------------------------------------+-----------+ -| :ref:`int` | :ref:`read_chunk_size` | ``4096`` | +| :ref:`int` | :ref:`read_chunk_size` | ``65536`` | +-------------------------------------+-------------------------------------------------------------------------------+-----------+ Methods @@ -458,7 +460,7 @@ The connection to use for this client. - :ref:`int` **read_chunk_size** +-----------+----------------------------+ -| *Default* | ``4096`` | +| *Default* | ``65536`` | +-----------+----------------------------+ | *Setter* | set_read_chunk_size(value) | +-----------+----------------------------+ diff --git a/classes/class_httprequest.rst b/classes/class_httprequest.rst index 217df7774..c52c12ea6 100644 --- a/classes/class_httprequest.rst +++ b/classes/class_httprequest.rst @@ -39,7 +39,7 @@ Can be used to make HTTP requests, i.e. download or upload files or web content # Note: Don't make simultaneous requests using a single HTTPRequest node. # The snippet below is provided for reference only. var body = {"name": "Godette"} - var error = http_request.request("https://httpbin.org/post", [], true, HTTPClient.METHOD_POST, body) + error = http_request.request("https://httpbin.org/post", [], true, HTTPClient.METHOD_POST, body) if error != OK: push_error("An error occurred in the HTTP request.") @@ -84,6 +84,8 @@ Can be used to make HTTP requests, i.e. download or upload files or web content **Note:** When performing HTTP requests from a project exported to HTML5, keep in mind the remote server may not allow requests from foreign origins due to `CORS `_. If you host the server in question, you should modify its backend to allow requests from foreign origins by adding the ``Access-Control-Allow-Origin: *`` HTTP header. +**Note:** SSL/TLS support is currently limited to TLS 1.0, TLS 1.1, and TLS 1.2. Attempting to connect to a TLS 1.3-only server will return an error. + Tutorials --------- @@ -97,7 +99,7 @@ Properties +-----------------------------+----------------------------------------------------------------------------+-----------+ | :ref:`int` | :ref:`body_size_limit` | ``-1`` | +-----------------------------+----------------------------------------------------------------------------+-----------+ -| :ref:`int` | :ref:`download_chunk_size` | ``4096`` | +| :ref:`int` | :ref:`download_chunk_size` | ``65536`` | +-----------------------------+----------------------------------------------------------------------------+-----------+ | :ref:`String` | :ref:`download_file` | ``""`` | +-----------------------------+----------------------------------------------------------------------------+-----------+ @@ -215,7 +217,7 @@ Maximum allowed size for response bodies. - :ref:`int` **download_chunk_size** +-----------+--------------------------------+ -| *Default* | ``4096`` | +| *Default* | ``65536`` | +-----------+--------------------------------+ | *Setter* | set_download_chunk_size(value) | +-----------+--------------------------------+ @@ -224,7 +226,7 @@ Maximum allowed size for response bodies. The size of the buffer used and maximum bytes to read per iteration. See :ref:`HTTPClient.read_chunk_size`. -Set this to a higher value (e.g. 65536 for 64 KiB) when downloading large files to achieve better speeds at the cost of memory. +Set this to a lower value (e.g. 4096 for 4 KiB) when downloading small files to decrease memory usage at the cost of download speeds. ---- diff --git a/classes/class_image.rst b/classes/class_image.rst index ef3135cce..26c94d206 100644 --- a/classes/class_image.rst +++ b/classes/class_image.rst @@ -16,9 +16,16 @@ Image datatype. Description ----------- -Native image datatype. Contains image data, which can be converted to a :ref:`Texture`, and several functions to interact with it. The maximum width and height for an ``Image`` are :ref:`MAX_WIDTH` and :ref:`MAX_HEIGHT`. +Native image datatype. Contains image data which can be converted to an :ref:`ImageTexture` and provides commonly used *image processing* methods. The maximum width and height for an ``Image`` are :ref:`MAX_WIDTH` and :ref:`MAX_HEIGHT`. -**Note:** The maximum image size is 16384×16384 pixels due to graphics hardware limitations. Larger images will fail to import. +An ``Image`` cannot be assigned to a ``texture`` property of an object directly (such as :ref:`Sprite`), and has to be converted manually to an :ref:`ImageTexture` first. + +**Note:** The maximum image size is 16384×16384 pixels due to graphics hardware limitations. Larger images may fail to import. + +Tutorials +--------- + +- :doc:`../getting_started/workflow/assets/importing_images` Properties ---------- @@ -101,6 +108,8 @@ Methods +-------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`load` **(** :ref:`String` path **)** | +-------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`load_bmp_from_buffer` **(** :ref:`PoolByteArray` buffer **)** | ++-------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`load_jpg_from_buffer` **(** :ref:`PoolByteArray` buffer **)** | +-------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`load_png_from_buffer` **(** :ref:`PoolByteArray` buffer **)** | @@ -117,7 +126,7 @@ Methods +-------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`resize` **(** :ref:`int` width, :ref:`int` height, :ref:`Interpolation` interpolation=1 **)** | +-------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`resize_to_po2` **(** :ref:`bool` square=false **)** | +| void | :ref:`resize_to_po2` **(** :ref:`bool` square=false, :ref:`Interpolation` interpolation=1 **)** | +-------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Image` | :ref:`rgbe_to_srgb` **(** **)** | +-------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -435,7 +444,7 @@ Property Descriptions | *Default* | ``{"data": PoolByteArray( ),"format": "Lum8","height": 0,"mipmaps": false,"width": 0}`` | +-----------+------------------------------------------------------------------------------------------+ -Holds all of the image's color data in a given format. See :ref:`Format` constants. +Holds all the image's color data in a given format. See :ref:`Format` constants. Method Descriptions ------------------- @@ -596,7 +605,7 @@ Flips the image vertically. - :ref:`Error` **generate_mipmaps** **(** :ref:`bool` renormalize=false **)** -Generates mipmaps for the image. Mipmaps are pre-calculated and lower resolution copies of the image. Mipmaps are automatically used if the image needs to be scaled down when rendered. This improves image quality and the performance of the rendering. Returns an error if the image is compressed, in a custom format or if the image's width/height is 0. +Generates mipmaps for the image. Mipmaps are precalculated and lower resolution copies of the image. Mipmaps are automatically used if the image needs to be scaled down when rendered. This improves image quality and the performance of the rendering. Returns an error if the image is compressed, in a custom format or if the image's width/height is 0. ---- @@ -716,7 +725,21 @@ Returns ``true`` if all the image's pixels have an alpha value of 0. Returns ``f - :ref:`Error` **load** **(** :ref:`String` path **)** -Loads an image from file ``path``. See `Supported image formats `_ for a list of supported image formats and limitations. +Loads an image from file ``path``. See `Supported image formats `_ for a list of supported image formats and limitations. + +**Warning:** This method should only be used in the editor or in cases when you need to load external images at run-time, such as images located at the ``user://`` directory, and may not work in exported projects. + +See also :ref:`ImageTexture` description for usage examples. + +---- + +.. _class_Image_method_load_bmp_from_buffer: + +- :ref:`Error` **load_bmp_from_buffer** **(** :ref:`PoolByteArray` buffer **)** + +Loads an image from the binary contents of a BMP file. + +**Note:** Godot's BMP module doesn't support 16-bit per pixel images. Only 1-bit, 4-bit, 8-bit, 24-bit, and 32-bit per pixel images are supported. ---- @@ -780,15 +803,15 @@ Multiplies color values with alpha values. Resulting color values for a pixel ar - void **resize** **(** :ref:`int` width, :ref:`int` height, :ref:`Interpolation` interpolation=1 **)** -Resizes the image to the given ``width`` and ``height``. New pixels are calculated using ``interpolation``. See ``interpolation`` constants. +Resizes the image to the given ``width`` and ``height``. New pixels are calculated using the ``interpolation`` mode defined via :ref:`Interpolation` constants. ---- .. _class_Image_method_resize_to_po2: -- void **resize_to_po2** **(** :ref:`bool` square=false **)** +- void **resize_to_po2** **(** :ref:`bool` square=false, :ref:`Interpolation` interpolation=1 **)** -Resizes the image to the nearest power of 2 for the width and height. If ``square`` is ``true`` then set width and height to be the same. +Resizes the image to the nearest power of 2 for the width and height. If ``square`` is ``true`` then set width and height to be the same. New pixels are calculated using the ``interpolation`` mode defined via :ref:`Interpolation` constants. ---- diff --git a/classes/class_imagetexture.rst b/classes/class_imagetexture.rst index e6f127e5f..b7a6b7503 100644 --- a/classes/class_imagetexture.rst +++ b/classes/class_imagetexture.rst @@ -16,9 +16,42 @@ A :ref:`Texture` based on an :ref:`Image`. Description ----------- -A :ref:`Texture` based on an :ref:`Image`. Can be created from an :ref:`Image` with :ref:`create_from_image`. +A :ref:`Texture` based on an :ref:`Image`. For an image to be displayed, an ``ImageTexture`` has to be created from it using the :ref:`create_from_image` method: -**Note:** The maximum image size is 16384×16384 pixels due to graphics hardware limitations. Larger images will fail to import. +:: + + var texture = ImageTexture.new() + var image = Image.new() + image.load("res://icon.png") + texture.create_from_image(image) + $Sprite.texture = texture + +This way, textures can be created at run-time by loading images both from within the editor and externally. + +**Warning:** Prefer to load imported textures with :ref:`@GDScript.load` over loading them from within the filesystem dynamically with :ref:`Image.load`, as it may not work in exported projects: + +:: + + var texture = load("res://icon.png") + $Sprite.texture = texture + +This is because images have to be imported as :ref:`StreamTexture` first to be loaded with :ref:`@GDScript.load`. If you'd still like to load an image file just like any other :ref:`Resource`, import it as an :ref:`Image` resource instead, and then load it normally using the :ref:`@GDScript.load` method. + +But do note that the image data can still be retrieved from an imported texture as well using the :ref:`Texture.get_data` method, which returns a copy of the data: + +:: + + var texture = load("res://icon.png") + var image : Image = texture.get_data() + +An ``ImageTexture`` is not meant to be operated from within the editor interface directly, and is mostly useful for rendering images on screen dynamically via code. If you need to generate images procedurally from within the editor, consider saving and importing images as custom texture resources implementing a new :ref:`EditorImportPlugin`. + +**Note:** The maximum texture size is 16384×16384 pixels due to graphics hardware limitations. + +Tutorials +--------- + +- :doc:`../getting_started/workflow/assets/importing_images` Properties ---------- @@ -117,7 +150,7 @@ Create a new ``ImageTexture`` with ``width`` and ``height``. - void **create_from_image** **(** :ref:`Image` image, :ref:`int` flags=7 **)** -Create a new ``ImageTexture`` from an :ref:`Image` with ``flags`` from :ref:`Flags`. An sRGB to linear color space conversion can take place, according to :ref:`Format`. +Initializes the texture by allocating and setting the data from an :ref:`Image` with ``flags`` from :ref:`Flags`. An sRGB to linear color space conversion can take place, according to :ref:`Format`. ---- @@ -125,7 +158,7 @@ Create a new ``ImageTexture`` from an :ref:`Image` with ``flags`` f - :ref:`Format` **get_format** **(** **)** |const| -Returns the format of the ``ImageTexture``, one of :ref:`Format`. +Returns the format of the texture, one of :ref:`Format`. ---- @@ -133,7 +166,9 @@ Returns the format of the ``ImageTexture``, one of :ref:`Format` **load** **(** :ref:`String` path **)** -Load an ``ImageTexture`` from a file path. +Loads an image from a file path and creates a texture from it. + +**Note:** the method is deprecated and will be removed in Godot 4.0, use :ref:`Image.load` and :ref:`create_from_image` instead. ---- @@ -141,7 +176,11 @@ Load an ``ImageTexture`` from a file path. - void **set_data** **(** :ref:`Image` image **)** -Sets the :ref:`Image` of this ``ImageTexture``. +Replaces the texture's data with a new :ref:`Image`. + +**Note:** The texture has to be initialized first with the :ref:`create_from_image` method before it can be updated. The new image dimensions, format, and mipmaps configuration should match the existing texture's image configuration, otherwise it has to be re-created with the :ref:`create_from_image` method. + +Use this method over :ref:`create_from_image` if you need to update the texture frequently, which is faster than allocating additional memory for a new texture each time. ---- @@ -149,7 +188,7 @@ Sets the :ref:`Image` of this ``ImageTexture``. - void **set_size_override** **(** :ref:`Vector2` size **)** -Resizes the ``ImageTexture`` to the specified dimensions. +Resizes the texture to the specified dimensions. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_immediategeometry.rst b/classes/class_immediategeometry.rst index 7e95002dd..225215803 100644 --- a/classes/class_immediategeometry.rst +++ b/classes/class_immediategeometry.rst @@ -24,6 +24,8 @@ See also :ref:`ArrayMesh`, :ref:`MeshDataTool`_ for front faces of triangle primitive modes. +**Note:** In case of missing points when handling large amounts of mesh data, try increasing its buffer size limit under :ref:`ProjectSettings.rendering/limits/buffers/immediate_buffer_size_kb`. + Methods ------- diff --git a/classes/class_input.rst b/classes/class_input.rst index b81ba9bf9..e60ed05d1 100644 --- a/classes/class_input.rst +++ b/classes/class_input.rst @@ -23,6 +23,10 @@ Tutorials - :doc:`../tutorials/inputs/index` +- `https://godotengine.org/asset-library/asset/515 `_ + +- `https://godotengine.org/asset-library/asset/676 `_ + Methods ------- @@ -251,11 +255,11 @@ Adds a new mapping entry (in SDL2 format) to the mapping database. Optionally up - :ref:`Vector3` **get_accelerometer** **(** **)** |const| -Returns the acceleration of the device's accelerometer, if the device has one. Otherwise, the method returns :ref:`Vector3.ZERO`. +Returns the acceleration of the device's accelerometer sensor, if the device has one. Otherwise, the method returns :ref:`Vector3.ZERO`. Note this method returns an empty :ref:`Vector3` when running from the editor even when your device has an accelerometer. You must export your project to a supported device to read values from the accelerometer. -**Note:** This method only works on iOS, Android, and UWP. On other platforms, it always returns :ref:`Vector3.ZERO`. +**Note:** This method only works on iOS, Android, and UWP. On other platforms, it always returns :ref:`Vector3.ZERO`. On Android the unit of measurement for each axis is m/s² while on iOS and UWP it's a multiple of the Earth's gravitational acceleration ``g`` (~9.81 m/s²). ---- @@ -287,9 +291,9 @@ Returns the currently assigned cursor shape (see :ref:`CursorShape` **get_gravity** **(** **)** |const| -Returns the gravity of the device's accelerometer, if the device has one. Otherwise, the method returns :ref:`Vector3.ZERO`. +Returns the gravity of the device's accelerometer sensor, if the device has one. Otherwise, the method returns :ref:`Vector3.ZERO`. -**Note:** This method only works on Android and iOS. On other platforms, it always returns :ref:`Vector3.ZERO`. +**Note:** This method only works on Android and iOS. On other platforms, it always returns :ref:`Vector3.ZERO`. On Android the unit of measurement for each axis is m/s² while on iOS it's a multiple of the Earth's gravitational acceleration ``g`` (~9.81 m/s²). ---- @@ -297,9 +301,9 @@ Returns the gravity of the device's accelerometer, if the device has one. Otherw - :ref:`Vector3` **get_gyroscope** **(** **)** |const| -Returns the rotation rate in rad/s around a device's X, Y, and Z axes of the gyroscope, if the device has one. Otherwise, the method returns :ref:`Vector3.ZERO`. +Returns the rotation rate in rad/s around a device's X, Y, and Z axes of the gyroscope sensor, if the device has one. Otherwise, the method returns :ref:`Vector3.ZERO`. -**Note:** This method only works on Android. On other platforms, it always returns :ref:`Vector3.ZERO`. +**Note:** This method only works on Android and iOS. On other platforms, it always returns :ref:`Vector3.ZERO`. ---- @@ -387,9 +391,9 @@ Returns the mouse speed for the last time the cursor was moved, and this until t - :ref:`Vector3` **get_magnetometer** **(** **)** |const| -Returns the the magnetic field strength in micro-Tesla for all axes of the device's magnetometer, if the device has one. Otherwise, the method returns :ref:`Vector3.ZERO`. +Returns the magnetic field strength in micro-Tesla for all axes of the device's magnetometer sensor, if the device has one. Otherwise, the method returns :ref:`Vector3.ZERO`. -**Note:** This method only works on Android and UWP. On other platforms, it always returns :ref:`Vector3.ZERO`. +**Note:** This method only works on Android, iOS and UWP. On other platforms, it always returns :ref:`Vector3.ZERO`. ---- @@ -572,7 +576,7 @@ Stops the vibration of the joypad. Vibrate Android and iOS devices. -**Note:** It needs VIBRATE permission for Android at export settings. iOS does not support duration. +**Note:** It needs ``VIBRATE`` permission for Android at export settings. iOS does not support duration. ---- diff --git a/classes/class_inputevent.rst b/classes/class_inputevent.rst index bbf69418f..20c7cd3b3 100644 --- a/classes/class_inputevent.rst +++ b/classes/class_inputevent.rst @@ -27,6 +27,10 @@ Tutorials - :doc:`../tutorials/2d/2d_transforms` +- `https://godotengine.org/asset-library/asset/515 `_ + +- `https://godotengine.org/asset-library/asset/676 `_ + Properties ---------- diff --git a/classes/class_inputeventaction.rst b/classes/class_inputeventaction.rst index 466f46fc9..f727b8478 100644 --- a/classes/class_inputeventaction.rst +++ b/classes/class_inputeventaction.rst @@ -23,6 +23,10 @@ Tutorials - `#actions <../tutorials/inputs/inputevent.html#actions>`_ in :doc:`../tutorials/inputs/inputevent` +- `https://godotengine.org/asset-library/asset/515 `_ + +- `https://godotengine.org/asset-library/asset/676 `_ + Properties ---------- @@ -81,7 +85,7 @@ If ``true``, the action's state is pressed. If ``false``, the action's state is | *Getter* | get_strength() | +-----------+---------------------+ -The action's strength between 0 and 1. This value is considered as equal to 0 if pressed is ``false``. The event strength allows faking analog joypad motion events, by precising how strongly is the joypad axis bent or pressed. +The action's strength between 0 and 1. This value is considered as equal to 0 if pressed is ``false``. The event strength allows faking analog joypad motion events, by specifying how strongly the joypad axis is bent or pressed. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_inputeventmousemotion.rst b/classes/class_inputeventmousemotion.rst index 1d4372acd..f60060966 100644 --- a/classes/class_inputeventmousemotion.rst +++ b/classes/class_inputeventmousemotion.rst @@ -25,6 +25,8 @@ Tutorials - :doc:`../tutorials/inputs/mouse_and_input_coordinates` +- `https://godotengine.org/asset-library/asset/676 `_ + Properties ---------- diff --git a/classes/class_instanceplaceholder.rst b/classes/class_instanceplaceholder.rst index 80a67c3c6..236f9b8a9 100644 --- a/classes/class_instanceplaceholder.rst +++ b/classes/class_instanceplaceholder.rst @@ -40,13 +40,15 @@ Method Descriptions - :ref:`Node` **create_instance** **(** :ref:`bool` replace=false, :ref:`PackedScene` custom_scene=null **)** +Not thread-safe. Use :ref:`Object.call_deferred` if calling from a thread. + ---- .. _class_InstancePlaceholder_method_get_instance_path: - :ref:`String` **get_instance_path** **(** **)** |const| -Gets the path to the :ref:`PackedScene` resource file that is loaded by default when calling :ref:`replace_by_instance`. +Gets the path to the :ref:`PackedScene` resource file that is loaded by default when calling :ref:`replace_by_instance`. Not thread-safe. Use :ref:`Object.call_deferred` if calling from a thread. ---- diff --git a/classes/class_int.rst b/classes/class_int.rst index 6ece4a666..7065ed32a 100644 --- a/classes/class_int.rst +++ b/classes/class_int.rst @@ -57,7 +57,7 @@ Cast a :ref:`bool` value to an integer value, ``int(true)`` will be - :ref:`int` **int** **(** :ref:`float` from **)** -Cast a float value to an integer value, this method simply removes the number fractions, so for example ``int(2.7)`` will be equals to 2, ``int(.1)`` will be equals to 0 and ``int(-2.7)`` will be equals to -2. +Cast a float value to an integer value, this method simply removes the number fractions (i.e. rounds ``from`` towards zero), so for example ``int(2.7)`` will be equals to 2, ``int(0.1)`` will be equals to 0 and ``int(-2.7)`` will be equals to -2. This operation is also called truncation. ---- diff --git a/classes/class_ip.rst b/classes/class_ip.rst index 45eb17a89..ffdc3d8bd 100644 --- a/classes/class_ip.rst +++ b/classes/class_ip.rst @@ -118,7 +118,7 @@ Removes a given item ``id`` from the queue. This should be used to free a queue - :ref:`Array` **get_local_addresses** **(** **)** |const| -Returns all of the user's current IPv4 and IPv6 addresses as an array. +Returns all the user's current IPv4 and IPv6 addresses as an array. ---- diff --git a/classes/class_itemlist.rst b/classes/class_itemlist.rst index f0997e5db..07fc2b33e 100644 --- a/classes/class_itemlist.rst +++ b/classes/class_itemlist.rst @@ -661,11 +661,6 @@ Select the item at the specified index. Sets the background color of the item specified by ``idx`` index to the specified :ref:`Color`. -:: - - var some_string = "Some text" - some_string.set_item_custom_bg_color(0,Color(1, 0, 0, 1) # This will set the background color of the first item of the control to red. - ---- .. _class_ItemList_method_set_item_custom_fg_color: @@ -674,11 +669,6 @@ Sets the background color of the item specified by ``idx`` index to the specifie Sets the foreground color of the item specified by ``idx`` index to the specified :ref:`Color`. -:: - - var some_string = "Some text" - some_string.set_item_custom_fg_color(0,Color(1, 0, 0, 1) # This will set the foreground color of the first item of the control to red. - ---- .. _class_ItemList_method_set_item_disabled: diff --git a/classes/class_javascript.rst b/classes/class_javascript.rst index 1cdb1998f..11a779c05 100644 --- a/classes/class_javascript.rst +++ b/classes/class_javascript.rst @@ -18,6 +18,8 @@ Description The JavaScript singleton is implemented only in the HTML5 export. It's used to access the browser's JavaScript context. This allows interaction with embedding pages or calling third-party JavaScript APIs. +**Note:** This singleton can be disabled at build-time to improve security. By default, the JavaScript singleton is enabled. Official export templates also have the JavaScript singleton enabled. See `Compiling for the Web `_ in the documentation for more information. + Tutorials --------- diff --git a/classes/class_joint.rst b/classes/class_joint.rst index 9f5a0cedf..5815f03cd 100644 --- a/classes/class_joint.rst +++ b/classes/class_joint.rst @@ -20,6 +20,11 @@ Description Joints are used to bind together two physics bodies. They have a solver priority and can define if the bodies of the two attached nodes should be able to collide with each other. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/524 `_ + Properties ---------- diff --git a/classes/class_kinematicbody.rst b/classes/class_kinematicbody.rst index 162c98622..3c0159103 100644 --- a/classes/class_kinematicbody.rst +++ b/classes/class_kinematicbody.rst @@ -20,13 +20,21 @@ Kinematic bodies are special types of bodies that are meant to be user-controlle **Simulated motion:** When these bodies are moved manually, either from code or from an :ref:`AnimationPlayer` (with :ref:`AnimationPlayer.playback_process_mode` set to "physics"), the physics will automatically compute an estimate of their linear and angular velocity. This makes them very useful for moving platforms or other AnimationPlayer-controlled objects (like a door, a bridge that opens, etc). -**Kinematic characters:** KinematicBody also has an API for moving objects (the :ref:`move_and_collide` and :ref:`move_and_slide` methods) while performing collision tests. This makes them really useful to implement characters that collide against a world, but that don't require advanced physics. +**Kinematic characters:** KinematicBody also has an API for moving objects (the :ref:`move_and_collide` and :ref:`move_and_slide` methods) while performing collision tests. This makes them really useful to implement characters that collide against a world, but don't require advanced physics. Tutorials --------- - :doc:`../tutorials/physics/kinematic_character_2d` +- `https://godotengine.org/asset-library/asset/126 `_ + +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/676 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- @@ -86,7 +94,13 @@ Property Descriptions | *Getter* | get_safe_margin() | +-----------+------------------------+ -If the body is at least this close to another body, this body will consider them to be colliding. +Extra margin used for collision recovery in motion functions (see :ref:`move_and_collide`, :ref:`move_and_slide`, :ref:`move_and_slide_with_snap`). + +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. + +A higher value means it's more flexible for detecting collision, which helps with consistently detecting walls and floors. + +A lower value forces the collision algorithm to use more exact detection, so it can be used in cases that specifically require precision, e.g at very low scale to avoid visible jittering, or for stability with a stack of kinematic bodies. ---- @@ -167,7 +181,7 @@ Returns the linear velocity of the floor at the last collision point. Only valid - :ref:`KinematicCollision` **get_slide_collision** **(** :ref:`int` slide_idx **)** -Returns a :ref:`KinematicCollision`, which contains information about a collision that occurred during the last :ref:`move_and_slide` call. 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_count` - 1). +Returns a :ref:`KinematicCollision`, which contains information about a collision that occurred during the last call to :ref:`move_and_slide` or :ref:`move_and_slide_with_snap`. 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_count` - 1). ---- @@ -175,7 +189,7 @@ Returns a :ref:`KinematicCollision`, which contains in - :ref:`int` **get_slide_count** **(** **)** |const| -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` or :ref:`move_and_slide_with_snap`. ---- @@ -183,7 +197,7 @@ Returns the number of times the body collided and changed direction during the l - :ref:`bool` **is_on_ceiling** **(** **)** |const| -Returns ``true`` if the body is on the ceiling. Only updates when calling :ref:`move_and_slide`. +Returns ``true`` if the body is on the ceiling. Only updates when calling :ref:`move_and_slide` or :ref:`move_and_slide_with_snap`. ---- @@ -191,7 +205,7 @@ Returns ``true`` if the body is on the ceiling. Only updates when calling :ref:` - :ref:`bool` **is_on_floor** **(** **)** |const| -Returns ``true`` if the body is on the floor. Only updates when calling :ref:`move_and_slide`. +Returns ``true`` if the body is on the floor. Only updates when calling :ref:`move_and_slide` or :ref:`move_and_slide_with_snap`. ---- @@ -199,7 +213,7 @@ Returns ``true`` if the body is on the floor. Only updates when calling :ref:`mo - :ref:`bool` **is_on_wall** **(** **)** |const| -Returns ``true`` if the body is on a wall. Only updates when calling :ref:`move_and_slide`. +Returns ``true`` if the body is on a wall. Only updates when calling :ref:`move_and_slide` or :ref:`move_and_slide_with_snap`. ---- @@ -217,7 +231,7 @@ If ``test_only`` is ``true``, the body does not move but the would-be collision - :ref:`Vector3` **move_and_slide** **(** :ref:`Vector3` linear_velocity, :ref:`Vector3` up_direction=Vector3( 0, 0, 0 ), :ref:`bool` stop_on_slope=false, :ref:`int` max_slides=4, :ref:`float` floor_max_angle=0.785398, :ref:`bool` infinite_inertia=true **)** -Moves the body along a vector. If the body collides with another, it will slide along the other body rather than stop immediately. If the other body is a ``KinematicBody`` or :ref:`RigidBody`, it will also be affected by the motion of the other body. You can use this to make moving or rotating platforms, or to make nodes push other nodes. +Moves the body along a vector. If the body collides with another, it will slide along the other body rather than stop immediately. If the other body is a ``KinematicBody`` or :ref:`RigidBody`, 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. This method should be used in :ref:`Node._physics_process` (or in a method called by :ref:`Node._physics_process`), as it uses the physics step's ``delta`` value automatically in calculations. Otherwise, the simulation will run at an incorrect speed. diff --git a/classes/class_kinematicbody2d.rst b/classes/class_kinematicbody2d.rst index 501fad3c5..739bd11f9 100644 --- a/classes/class_kinematicbody2d.rst +++ b/classes/class_kinematicbody2d.rst @@ -20,7 +20,7 @@ Kinematic bodies are special types of bodies that are meant to be user-controlle **Simulated motion:** When these bodies are moved manually, either from code or from an :ref:`AnimationPlayer` (with :ref:`AnimationPlayer.playback_process_mode` set to "physics"), the physics will automatically compute an estimate of their linear and angular velocity. This makes them very useful for moving platforms or other AnimationPlayer-controlled objects (like a door, a bridge that opens, etc). -**Kinematic characters:** KinematicBody2D also has an API for moving objects (the :ref:`move_and_collide` and :ref:`move_and_slide` methods) while performing collision tests. This makes them really useful to implement characters that collide against a world, but that don't require advanced physics. +**Kinematic characters:** KinematicBody2D also has an API for moving objects (the :ref:`move_and_collide` and :ref:`move_and_slide` methods) while performing collision tests. This makes them really useful to implement characters that collide against a world, but don't require advanced physics. Tutorials --------- @@ -29,6 +29,10 @@ Tutorials - :doc:`../tutorials/physics/using_kinematic_body_2d` +- `https://godotengine.org/asset-library/asset/113 `_ + +- `https://godotengine.org/asset-library/asset/120 `_ + Properties ---------- @@ -80,7 +84,13 @@ Property Descriptions | *Getter* | get_safe_margin() | +-----------+------------------------+ -If the body is at least this close to another body, this body will consider them to be colliding. +Extra margin used for collision recovery in motion functions (see :ref:`move_and_collide`, :ref:`move_and_slide`, :ref:`move_and_slide_with_snap`). + +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. + +A higher value means it's more flexible for detecting collision, which helps with consistently detecting walls and floors. + +A lower value forces the collision algorithm to use more exact detection, so it can be used in cases that specifically require precision, e.g at very low scale to avoid visible jittering, or for stability with a stack of kinematic bodies. ---- @@ -121,7 +131,7 @@ Returns the linear velocity of the floor at the last collision point. Only valid - :ref:`KinematicCollision2D` **get_slide_collision** **(** :ref:`int` slide_idx **)** -Returns a :ref:`KinematicCollision2D`, which contains information about a collision that occurred during the last :ref:`move_and_slide` call. 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_count` - 1). +Returns a :ref:`KinematicCollision2D`, which contains information about a collision that occurred during the last call to :ref:`move_and_slide` or :ref:`move_and_slide_with_snap`. 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_count` - 1). **Example usage:** @@ -137,7 +147,7 @@ Returns a :ref:`KinematicCollision2D`, which contain - :ref:`int` **get_slide_count** **(** **)** |const| -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` or :ref:`move_and_slide_with_snap`. ---- @@ -145,7 +155,7 @@ Returns the number of times the body collided and changed direction during the l - :ref:`bool` **is_on_ceiling** **(** **)** |const| -Returns ``true`` if the body is on the ceiling. Only updates when calling :ref:`move_and_slide`. +Returns ``true`` if the body is on the ceiling. Only updates when calling :ref:`move_and_slide` or :ref:`move_and_slide_with_snap`. ---- @@ -153,7 +163,7 @@ Returns ``true`` if the body is on the ceiling. Only updates when calling :ref:` - :ref:`bool` **is_on_floor** **(** **)** |const| -Returns ``true`` if the body is on the floor. Only updates when calling :ref:`move_and_slide`. +Returns ``true`` if the body is on the floor. Only updates when calling :ref:`move_and_slide` or :ref:`move_and_slide_with_snap`. ---- @@ -161,7 +171,7 @@ Returns ``true`` if the body is on the floor. Only updates when calling :ref:`mo - :ref:`bool` **is_on_wall** **(** **)** |const| -Returns ``true`` if the body is on a wall. Only updates when calling :ref:`move_and_slide`. +Returns ``true`` if the body is on a wall. Only updates when calling :ref:`move_and_slide` or :ref:`move_and_slide_with_snap`. ---- @@ -179,7 +189,7 @@ If ``test_only`` is ``true``, the body does not move but the would-be collision - :ref:`Vector2` **move_and_slide** **(** :ref:`Vector2` linear_velocity, :ref:`Vector2` up_direction=Vector2( 0, 0 ), :ref:`bool` stop_on_slope=false, :ref:`int` max_slides=4, :ref:`float` floor_max_angle=0.785398, :ref:`bool` infinite_inertia=true **)** -Moves the body along a vector. If the body collides with another, it will slide along the other body rather than stop immediately. If the other body is a ``KinematicBody2D`` or :ref:`RigidBody2D`, it will also be affected by the motion of the other body. You can use this to make moving or rotating platforms, or to make nodes push other nodes. +Moves the body along a vector. If the body collides with another, it will slide along the other body rather than stop immediately. If the other body is a ``KinematicBody2D`` 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. This method should be used in :ref:`Node._physics_process` (or in a method called by :ref:`Node._physics_process`), as it uses the physics step's ``delta`` value automatically in calculations. Otherwise, the simulation will run at an incorrect speed. diff --git a/classes/class_label.rst b/classes/class_label.rst index ffa27d3ea..01cb56d9e 100644 --- a/classes/class_label.rst +++ b/classes/class_label.rst @@ -20,6 +20,11 @@ Label displays plain text on the screen. It gives you control over the horizonta **Note:** Contrarily to most other :ref:`Control`\ s, Label's :ref:`Control.mouse_filter` defaults to :ref:`Control.MOUSE_FILTER_IGNORE` (i.e. it doesn't react to mouse input events). This implies that a label won't display any configured :ref:`Control.hint_tooltip`, unless you change its mouse filter. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/515 `_ + Properties ---------- diff --git a/classes/class_light.rst b/classes/class_light.rst index c505753ea..38eb395a6 100644 --- a/classes/class_light.rst +++ b/classes/class_light.rst @@ -25,6 +25,8 @@ Tutorials - :doc:`../tutorials/3d/lights_and_shadows` +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_line2d.rst b/classes/class_line2d.rst index 61cb63d85..8ceaa274d 100644 --- a/classes/class_line2d.rst +++ b/classes/class_line2d.rst @@ -20,6 +20,13 @@ A line through several points in 2D space. **Note:** By default, Godot can only draw up to 4,096 polygon points at a time. To increase this limit, open the Project Settings and increase :ref:`ProjectSettings.rendering/limits/buffers/canvas_polygon_buffer_size_kb` and :ref:`ProjectSettings.rendering/limits/buffers/canvas_polygon_index_buffer_size_kb`. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/584 `_ + +- `https://godotengine.org/asset-library/asset/583 `_ + Properties ---------- diff --git a/classes/class_lineedit.rst b/classes/class_lineedit.rst index ae94a041b..7b224465d 100644 --- a/classes/class_lineedit.rst +++ b/classes/class_lineedit.rst @@ -117,6 +117,8 @@ Methods +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PopupMenu` | :ref:`get_menu` **(** **)** |const| | +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_scroll_offset` **(** **)** |const| | ++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`menu_option` **(** :ref:`int` option **)** | +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`select` **(** :ref:`int` from=0, :ref:`int` to=-1 **)** | @@ -583,6 +585,14 @@ Returns the :ref:`PopupMenu` of this ``LineEdit``. By default, ---- +.. _class_LineEdit_method_get_scroll_offset: + +- :ref:`int` **get_scroll_offset** **(** **)** |const| + +Returns the scroll offset due to :ref:`caret_position`, as a number of characters. + +---- + .. _class_LineEdit_method_menu_option: - void **menu_option** **(** :ref:`int` option **)** diff --git a/classes/class_linkbutton.rst b/classes/class_linkbutton.rst index 57f360a9d..b2daf0e55 100644 --- a/classes/class_linkbutton.rst +++ b/classes/class_linkbutton.rst @@ -18,11 +18,11 @@ Description This kind of button is primarily used when the interaction with the button causes a context change (like linking to a web page). +See also :ref:`BaseButton` which contains common properties and methods associated with this node. + Properties ---------- -+-----------------------------------------------------+-------------------------------------------------------+---------------------------+ -| :ref:`FocusMode` | enabled_focus_mode | ``0`` *(parent override)* | +-----------------------------------------------------+-------------------------------------------------------+---------------------------+ | :ref:`FocusMode` | focus_mode | ``0`` *(parent override)* | +-----------------------------------------------------+-------------------------------------------------------+---------------------------+ diff --git a/classes/class_mainloop.rst b/classes/class_mainloop.rst index eb0b3742c..1368523d0 100644 --- a/classes/class_mainloop.rst +++ b/classes/class_mainloop.rst @@ -249,7 +249,7 @@ Deprecated callback, does not do anything. Use :ref:`_input_event` **_iteration** **(** :ref:`float` delta **)** |virtual| -Called each physics frame with the time since the last physics frame as argument (in seconds). Equivalent to :ref:`Node._physics_process`. +Called each physics frame with the time since the last physics frame as argument (``delta``, in seconds). Equivalent to :ref:`Node._physics_process`. If implemented, the method must return a boolean value. ``true`` ends the main loop, while ``false`` lets it proceed to the next frame. diff --git a/classes/class_margincontainer.rst b/classes/class_margincontainer.rst index 7a95b3ddb..4dfee83e2 100644 --- a/classes/class_margincontainer.rst +++ b/classes/class_margincontainer.rst @@ -22,11 +22,12 @@ Adds a top, left, bottom, and right margin to all :ref:`Control` :: + # This code sample assumes the current script is extending MarginContainer. var margin_value = 100 - set("custom_constants/margin_top", margin_value) - set("custom_constants/margin_left", margin_value) - set("custom_constants/margin_bottom", margin_value) - set("custom_constants/margin_right", margin_value) + add_constant_override("margin_top", margin_value) + add_constant_override("margin_left", margin_value) + add_constant_override("margin_bottom", margin_value) + add_constant_override("margin_right", margin_value) Theme Properties ---------------- diff --git a/classes/class_material.rst b/classes/class_material.rst index a23fc7581..48d7cbeea 100644 --- a/classes/class_material.rst +++ b/classes/class_material.rst @@ -20,6 +20,13 @@ Description Material is a base :ref:`Resource` used for coloring and shading geometry. All materials inherit from it and almost all :ref:`VisualInstance` derived nodes carry a Material. A few flags and parameters are shared between all material types and are configured here. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/123 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_menubutton.rst b/classes/class_menubutton.rst index c286b4705..04f04b3b6 100644 --- a/classes/class_menubutton.rst +++ b/classes/class_menubutton.rst @@ -18,7 +18,9 @@ Description Special button that brings up a :ref:`PopupMenu` when clicked. -New items can be created inside this :ref:`PopupMenu` using ``get_popup().add_item("My Item Name")``. You can also create them directly from the editor. To do so, select the ``MenuButton`` node, then in the toolbar at the top of the 2D editor, click **Items** then click **Add** in the popup. You will be able to give each items new properties. +New items can be created inside this :ref:`PopupMenu` using ``get_popup().add_item("My Item Name")``. You can also create them directly from the editor. To do so, select the ``MenuButton`` node, then in the toolbar at the top of the 2D editor, click **Items** then click **Add** in the popup. You will be able to give each item new properties. + +See also :ref:`BaseButton` which contains common properties and methods associated with this node. Properties ---------- @@ -26,8 +28,6 @@ Properties +-----------------------------------------------+-------------------------------------------------------------------+------------------------------+ | :ref:`ActionMode` | action_mode | ``0`` *(parent override)* | +-----------------------------------------------+-------------------------------------------------------------------+------------------------------+ -| :ref:`FocusMode` | enabled_focus_mode | ``0`` *(parent override)* | -+-----------------------------------------------+-------------------------------------------------------------------+------------------------------+ | :ref:`bool` | flat | ``true`` *(parent override)* | +-----------------------------------------------+-------------------------------------------------------------------+------------------------------+ | :ref:`FocusMode` | focus_mode | ``0`` *(parent override)* | diff --git a/classes/class_mesh.rst b/classes/class_mesh.rst index 7a66317ef..6f92844ea 100644 --- a/classes/class_mesh.rst +++ b/classes/class_mesh.rst @@ -20,6 +20,17 @@ Description Mesh is a type of :ref:`Resource` that contains vertex array-based geometry, divided in *surfaces*. Each surface contains a completely separate array and a material used to draw it. Design wise, a mesh with multiple surfaces is preferred to a single surface, because objects created in 3D editing software commonly contain multiple materials. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/123 `_ + +- `https://godotengine.org/asset-library/asset/126 `_ + +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- @@ -258,7 +269,7 @@ Property Descriptions | *Getter* | get_lightmap_size_hint() | +-----------+-------------------------------+ -Sets a hint to be used for lightmap resolution in :ref:`BakedLightmap`. Overrides :ref:`BakedLightmap.bake_default_texels_per_unit`. +Sets a hint to be used for lightmap resolution in :ref:`BakedLightmap`. Overrides :ref:`BakedLightmap.default_texels_per_unit`. Method Descriptions ------------------- diff --git a/classes/class_meshdatatool.rst b/classes/class_meshdatatool.rst index 1a518059a..08f7a97a0 100644 --- a/classes/class_meshdatatool.rst +++ b/classes/class_meshdatatool.rst @@ -24,14 +24,21 @@ Below is an example of how MeshDataTool may be used. :: + var mesh = ArrayMesh.new() + mesh.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, CubeMesh.new().get_mesh_arrays()) var mdt = MeshDataTool.new() mdt.create_from_surface(mesh, 0) for i in range(mdt.get_vertex_count()): var vertex = mdt.get_vertex(i) - ... + # In this example we extend the mesh by one unit, which results in seperated faces as it is flat shaded. + vertex += mdt.get_vertex_normal(i) + # Save your change. mdt.set_vertex(i, vertex) mesh.surface_remove(0) mdt.commit_to_surface(mesh) + var mi = MeshInstance.new() + mi.mesh = mesh + add_child(mi) See also :ref:`ArrayMesh`, :ref:`ImmediateGeometry` and :ref:`SurfaceTool` for procedural geometry generation. diff --git a/classes/class_meshinstance.rst b/classes/class_meshinstance.rst index 9b80cc762..17a19e019 100644 --- a/classes/class_meshinstance.rst +++ b/classes/class_meshinstance.rst @@ -20,16 +20,29 @@ Description MeshInstance is a node that takes a :ref:`Mesh` resource and adds it to the current scenario by creating an instance of it. This is the class most often used to get 3D geometry rendered and can be used to instance a single :ref:`Mesh` in many places. This allows to reuse geometry and save on resources. When a :ref:`Mesh` has to be instanced more than thousands of times at close proximity, consider using a :ref:`MultiMesh` in a :ref:`MultiMeshInstance` instead. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/123 `_ + +- `https://godotengine.org/asset-library/asset/126 `_ + +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- -+---------------------------------+-------------------------------------------------------+--------------------+ -| :ref:`Mesh` | :ref:`mesh` | | -+---------------------------------+-------------------------------------------------------+--------------------+ -| :ref:`NodePath` | :ref:`skeleton` | ``NodePath("..")`` | -+---------------------------------+-------------------------------------------------------+--------------------+ -| :ref:`Skin` | :ref:`skin` | | -+---------------------------------+-------------------------------------------------------+--------------------+ ++---------------------------------+-------------------------------------------------------------------------------------------------------------+--------------------+ +| :ref:`Mesh` | :ref:`mesh` | | ++---------------------------------+-------------------------------------------------------------------------------------------------------------+--------------------+ +| :ref:`NodePath` | :ref:`skeleton` | ``NodePath("..")`` | ++---------------------------------+-------------------------------------------------------------------------------------------------------------+--------------------+ +| :ref:`Skin` | :ref:`skin` | | ++---------------------------------+-------------------------------------------------------------------------------------------------------------+--------------------+ +| :ref:`bool` | :ref:`software_skinning_transform_normals` | ``true`` | ++---------------------------------+-------------------------------------------------------------------------------------------------------------+--------------------+ Methods ------- @@ -41,6 +54,8 @@ Methods +---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`create_trimesh_collision` **(** **)** | +---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Material` | :ref:`get_active_material` **(** :ref:`int` surface **)** |const| | ++---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Material` | :ref:`get_surface_material` **(** :ref:`int` surface **)** |const| | +---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_surface_material_count` **(** **)** |const| | @@ -93,6 +108,24 @@ The :ref:`Mesh` resource for the instance. Sets the skin to be used by this instance. +---- + +.. _class_MeshInstance_property_software_skinning_transform_normals: + +- :ref:`bool` **software_skinning_transform_normals** + ++-----------+--------------------------------------------------+ +| *Default* | ``true`` | ++-----------+--------------------------------------------------+ +| *Setter* | set_software_skinning_transform_normals(value) | ++-----------+--------------------------------------------------+ +| *Getter* | is_software_skinning_transform_normals_enabled() | ++-----------+--------------------------------------------------+ + +If ``true``, normals are transformed when software skinning is used. Set to ``false`` when normals are not needed for better performance. + +See :ref:`ProjectSettings.rendering/quality/skinning/software_skinning_fallback` for details about how software skinning is enabled. + Method Descriptions ------------------- @@ -120,6 +153,14 @@ This helper creates a :ref:`StaticBody` child node with a :ref ---- +.. _class_MeshInstance_method_get_active_material: + +- :ref:`Material` **get_active_material** **(** :ref:`int` surface **)** |const| + +Returns the :ref:`Material` that will be used by the :ref:`Mesh` when drawing. This can return the :ref:`GeometryInstance.material_override`, the surface override :ref:`Material` defined in this ``MeshInstance``, or the surface :ref:`Material` defined in the :ref:`Mesh`. For example, if :ref:`GeometryInstance.material_override` is used, all surfaces will return the override material. + +---- + .. _class_MeshInstance_method_get_surface_material: - :ref:`Material` **get_surface_material** **(** :ref:`int` surface **)** |const| diff --git a/classes/class_meshlibrary.rst b/classes/class_meshlibrary.rst index d2d7c6fea..2ab3262ed 100644 --- a/classes/class_meshlibrary.rst +++ b/classes/class_meshlibrary.rst @@ -18,6 +18,13 @@ Description A library of meshes. Contains a list of :ref:`Mesh` resources, each with a name and ID. Each item can also include collision and navigation shapes. This resource is used in :ref:`GridMap`. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/126 `_ + +- `https://godotengine.org/asset-library/asset/125 `_ + Methods ------- diff --git a/classes/class_multimesh.rst b/classes/class_multimesh.rst index 1549abbe4..7946421ad 100644 --- a/classes/class_multimesh.rst +++ b/classes/class_multimesh.rst @@ -20,7 +20,7 @@ MultiMesh provides low-level mesh instancing. Drawing thousands of :ref:`MeshIns MultiMesh is much faster as it can draw thousands of instances with a single draw call, resulting in less API overhead. -As a drawback, if the instances are too far away of each other, performance may be reduced as every single instance will always rendered (they are spatially indexed as one, for the whole object). +As a drawback, if the instances are too far away of each other, performance may be reduced as every single instance will always render (they are spatially indexed as one, for the whole object). Since instances may have any behavior, the AABB used for visibility must be provided by the user. @@ -278,7 +278,7 @@ All data is packed in one large float array. An array may look like this: Transf - void **set_instance_color** **(** :ref:`int` instance, :ref:`Color` color **)** -Sets the color of a specific instance. +Sets the color of a specific instance by *multiplying* the mesh's existing vertex colors. For the color to take effect, ensure that :ref:`color_format` is non-``null`` on the ``MultiMesh`` and :ref:`SpatialMaterial.vertex_color_use_as_albedo` is ``true`` on the material. diff --git a/classes/class_multiplayerapi.rst b/classes/class_multiplayerapi.rst index 0084993db..9611ae20c 100644 --- a/classes/class_multiplayerapi.rst +++ b/classes/class_multiplayerapi.rst @@ -16,12 +16,14 @@ High-level multiplayer API. Description ----------- -This class implements most of the logic behind the high-level multiplayer API. +This class implements most of the logic behind the high-level multiplayer API. See also :ref:`NetworkedMultiplayerPeer`. By default, :ref:`SceneTree` has a reference to this class that is used to provide multiplayer capabilities (i.e. RPC/RSET) across the whole scene. It is possible to override the MultiplayerAPI instance used by specific Nodes by setting the :ref:`Node.custom_multiplayer` property, effectively allowing to run both client and server in the same scene. +**Note:** The high-level multiplayer API protocol is an implementation detail and isn't meant to be used by non-Godot servers. It may change without notice. + Properties ---------- @@ -32,6 +34,8 @@ Properties +-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+-----------+ | :ref:`bool` | :ref:`refuse_new_network_connections` | ``false`` | +-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+-----------+ +| :ref:`Node` | :ref:`root_node` | | ++-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+-----------+ Methods ------- @@ -53,8 +57,6 @@ Methods +-----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`send_bytes` **(** :ref:`PoolByteArray` bytes, :ref:`int` id=0, :ref:`TransferMode` mode=2 **)** | +-----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_root_node` **(** :ref:`Node` node **)** | -+-----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Signals ------- @@ -197,6 +199,22 @@ The peer object to handle the RPC system (effectively enabling networking when s If ``true``, the MultiplayerAPI's :ref:`network_peer` refuses new incoming connections. +---- + +.. _class_MultiplayerAPI_property_root_node: + +- :ref:`Node` **root_node** + ++----------+----------------------+ +| *Setter* | set_root_node(value) | ++----------+----------------------+ +| *Getter* | get_root_node() | ++----------+----------------------+ + +The root node to use for RPCs. Instead of an absolute path, a relative path will be used to find the node upon which the RPC should be executed. + +This effectively allows to have different branches of the scene tree to be managed by different MultiplayerAPI, allowing for example to run both client and server in the same scene. + Method Descriptions ------------------- @@ -266,16 +284,6 @@ Method used for polling the MultiplayerAPI. You only need to worry about this if Sends the given raw ``bytes`` to a specific peer identified by ``id`` (see :ref:`NetworkedMultiplayerPeer.set_target_peer`). Default ID is ``0``, i.e. broadcast to all peers. ----- - -.. _class_MultiplayerAPI_method_set_root_node: - -- void **set_root_node** **(** :ref:`Node` node **)** - -Sets the base root node to use for RPCs. Instead of an absolute path, a relative path will be used to find the node upon which the RPC should be executed. - -This effectively allows to have different branches of the scene tree to be managed by different MultiplayerAPI, allowing for example to run both client and server in the same scene. - .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_navigation.rst b/classes/class_navigation.rst index 6e88e86e1..c73f72daa 100644 --- a/classes/class_navigation.rst +++ b/classes/class_navigation.rst @@ -18,6 +18,11 @@ Description Provides navigation and pathfinding within a collection of :ref:`NavigationMesh`\ es. By default, these will be automatically collected from child :ref:`NavigationMeshInstance` nodes, but they can also be added on the fly with :ref:`navmesh_add`. In addition to basic pathfinding, this class also assists with aligning navigation agents with the meshes they are navigating on. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/124 `_ + Properties ---------- diff --git a/classes/class_navigation2d.rst b/classes/class_navigation2d.rst index f3f33066a..ed92e719c 100644 --- a/classes/class_navigation2d.rst +++ b/classes/class_navigation2d.rst @@ -18,6 +18,11 @@ Description Navigation2D provides navigation and pathfinding within a 2D area, specified as a collection of :ref:`NavigationPolygon` resources. By default, these are automatically collected from child :ref:`NavigationPolygonInstance` nodes, but they can also be added on the fly with :ref:`navpoly_add`. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/117 `_ + Methods ------- diff --git a/classes/class_navigationmesh.rst b/classes/class_navigationmesh.rst index dfdcce267..d589dee97 100644 --- a/classes/class_navigationmesh.rst +++ b/classes/class_navigationmesh.rst @@ -13,6 +13,11 @@ NavigationMesh +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/124 `_ + Properties ---------- diff --git a/classes/class_navigationpolygon.rst b/classes/class_navigationpolygon.rst index 90d380181..2ed409290 100644 --- a/classes/class_navigationpolygon.rst +++ b/classes/class_navigationpolygon.rst @@ -39,6 +39,11 @@ Using :ref:`add_polygon` and indices polygon.add_polygon(indices) $NavigationPolygonInstance.navpoly = polygon +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/117 `_ + Methods ------- diff --git a/classes/class_networkedmultiplayerenet.rst b/classes/class_networkedmultiplayerenet.rst index 5452221b8..7ee7e6d8a 100644 --- a/classes/class_networkedmultiplayerenet.rst +++ b/classes/class_networkedmultiplayerenet.rst @@ -18,6 +18,10 @@ Description A PacketPeer implementation that should be passed to :ref:`SceneTree.network_peer` after being initialized as either a client or server. Events can then be handled by connecting to :ref:`SceneTree` signals. +ENet's purpose is to provide a relatively thin, simple and robust network communication layer on top of UDP (User Datagram Protocol). + +**Note:** ENet only uses UDP, not TCP. When forwarding the server port to make your server accessible on the public Internet, you only need to forward the server port in UDP. You can use the :ref:`UPNP` class to try to forward the server port automatically when starting the server. + Tutorials --------- @@ -74,6 +78,8 @@ Methods +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_dtls_key` **(** :ref:`CryptoKey` key **)** | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_peer_timeout` **(** :ref:`int` id, :ref:`int` timeout_limit, :ref:`int` timeout_min, :ref:`int` timeout_max **)** | ++---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Enumerations ------------ @@ -165,7 +171,7 @@ The compression method used for network packets. These have different tradeoffs | *Getter* | is_dtls_verify_enabled() | +-----------+--------------------------------+ -Enable or disable certiticate verification when :ref:`use_dtls` ``true``. +Enable or disable certificate verification when :ref:`use_dtls` ``true``. ---- @@ -306,6 +312,16 @@ Configure the :ref:`X509Certificate` to use when :ref:`us Configure the :ref:`CryptoKey` to use when :ref:`use_dtls` is ``true``. Remember to also call :ref:`set_dtls_certificate` to setup your :ref:`X509Certificate`. +---- + +.. _class_NetworkedMultiplayerENet_method_set_peer_timeout: + +- void **set_peer_timeout** **(** :ref:`int` id, :ref:`int` timeout_limit, :ref:`int` timeout_min, :ref:`int` timeout_max **)** + +Sets the timeout parameters for a peer. The timeout parameters control how and when a peer will timeout from a failure to acknowledge reliable traffic. Timeout values are expressed in milliseconds. + +The ``timeout_limit`` is a factor that, multiplied by a value based on the avarage round trip time, will determine the timeout limit for a reliable packet. When that limit is reached, the timeout will be doubled, and the peer will be disconnected if that limit has reached ``timeout_min``. The ``timeout_max`` parameter, on the other hand, defines a fixed timeout for which any packet must be acknowledged or the peer will be dropped. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_networkedmultiplayerpeer.rst b/classes/class_networkedmultiplayerpeer.rst index 0aaf95716..7948ff1cf 100644 --- a/classes/class_networkedmultiplayerpeer.rst +++ b/classes/class_networkedmultiplayerpeer.rst @@ -18,13 +18,17 @@ A high-level network interface to simplify multiplayer interactions. Description ----------- -Manages the connection to network peers. Assigns unique IDs to each client connected to the server. +Manages the connection to network peers. Assigns unique IDs to each client connected to the server. See also :ref:`MultiplayerAPI`. + +**Note:** The high-level multiplayer API protocol is an implementation detail and isn't meant to be used by non-Godot servers. It may change without notice. Tutorials --------- - :doc:`../tutorials/networking/high_level_multiplayer` +- `https://godotengine.org/asset-library/asset/537 `_ + Properties ---------- diff --git a/classes/class_ninepatchrect.rst b/classes/class_ninepatchrect.rst index 65ec096c9..ba3b570a9 100644 --- a/classes/class_ninepatchrect.rst +++ b/classes/class_ninepatchrect.rst @@ -74,11 +74,15 @@ Enumerations enum **AxisStretchMode**: -- **AXIS_STRETCH_MODE_STRETCH** = **0** --- Doesn't do anything at the time of writing. +- **AXIS_STRETCH_MODE_STRETCH** = **0** --- Stretches the center texture across the NinePatchRect. This may cause the texture to be distorted. -- **AXIS_STRETCH_MODE_TILE** = **1** --- Doesn't do anything at the time of writing. +- **AXIS_STRETCH_MODE_TILE** = **1** --- Repeats the center texture across the NinePatchRect. This won't cause any visible distortion. The texture must be seamless for this to work without displaying artifacts between edges. -- **AXIS_STRETCH_MODE_TILE_FIT** = **2** --- Doesn't do anything at the time of writing. +**Note:** Only supported when using the GLES3 renderer. When using the GLES2 renderer, this will behave like :ref:`AXIS_STRETCH_MODE_STRETCH`. + +- **AXIS_STRETCH_MODE_TILE_FIT** = **2** --- Repeats the center texture across the NinePatchRect, but will also stretch the texture to make sure each tile is visible in full. This may cause the texture to be distorted, but less than :ref:`AXIS_STRETCH_MODE_STRETCH`. The texture must be seamless for this to work without displaying artifacts between edges. + +**Note:** Only supported when using the GLES3 renderer. When using the GLES2 renderer, this will behave like :ref:`AXIS_STRETCH_MODE_STRETCH`. Property Descriptions --------------------- @@ -95,7 +99,7 @@ Property Descriptions | *Getter* | get_h_axis_stretch_mode() | +-----------+--------------------------------+ -Doesn't do anything at the time of writing. +The stretch mode to use for horizontal stretching/tiling. See :ref:`AxisStretchMode` for possible values. ---- @@ -111,7 +115,7 @@ Doesn't do anything at the time of writing. | *Getter* | get_v_axis_stretch_mode() | +-----------+--------------------------------+ -Doesn't do anything at the time of writing. +The stretch mode to use for vertical stretching/tiling. See :ref:`AxisStretchMode` for possible values. ---- @@ -159,7 +163,7 @@ The height of the 9-slice's bottom row. A margin of 16 means the 9-slice's botto | *Getter* | get_patch_margin() | +-----------+-------------------------+ -The height of the 9-slice's left column. +The width of the 9-slice's left column. A margin of 16 means the 9-slice's left corners and side will have a width of 16 pixels. You can set all 4 margin values individually to create panels with non-uniform borders. ---- @@ -175,7 +179,7 @@ The height of the 9-slice's left column. | *Getter* | get_patch_margin() | +-----------+-------------------------+ -The height of the 9-slice's right column. +The width of the 9-slice's right column. A margin of 16 means the 9-slice's right corners and side will have a width of 16 pixels. You can set all 4 margin values individually to create panels with non-uniform borders. ---- @@ -191,7 +195,7 @@ The height of the 9-slice's right column. | *Getter* | get_patch_margin() | +-----------+-------------------------+ -The height of the 9-slice's top row. +The height of the 9-slice's top row. A margin of 16 means the 9-slice's top corners and side will have a height of 16 pixels. You can set all 4 margin values individually to create panels with non-uniform borders. ---- diff --git a/classes/class_node.rst b/classes/class_node.rst index 3c43498eb..eb5ffa481 100644 --- a/classes/class_node.rst +++ b/classes/class_node.rst @@ -28,7 +28,7 @@ Once all nodes have been added in the scene tree, they receive the :ref:`NOTIFIC This means that when adding a node to the scene tree, the following order will be used for the callbacks: :ref:`_enter_tree` of the parent, :ref:`_enter_tree` of the children, :ref:`_ready` of the children and finally :ref:`_ready` of the parent (recursively for the entire scene tree). -**Processing:** Nodes can override the "process" state, so that they receive a callback on each frame requesting them to process (do something). Normal processing (callback :ref:`_process`, toggled with :ref:`set_process`) happens as fast as possible and is dependent on the frame rate, so the processing time *delta* is passed as an argument. Physics processing (callback :ref:`_physics_process`, toggled with :ref:`set_physics_process`) happens a fixed number of times per second (60 by default) and is useful for code related to the physics engine. +**Processing:** Nodes can override the "process" state, so that they receive a callback on each frame requesting them to process (do something). Normal processing (callback :ref:`_process`, toggled with :ref:`set_process`) happens as fast as possible and is dependent on the frame rate, so the processing time *delta* (in seconds) is passed as an argument. Physics processing (callback :ref:`_physics_process`, toggled with :ref:`set_physics_process`) happens a fixed number of times per second (60 by default) and is useful for code related to the physics engine. Nodes can also process input events. When present, the :ref:`_input` function will be called for each input that the program receives. In many cases, this can be overkill (unless used for simple projects), and the :ref:`_unhandled_input` function might be preferred; it is called when the input event was not handled by anyone else (typically, GUI :ref:`Control` nodes), ensuring that the node only receives the events that were meant for it. @@ -45,6 +45,8 @@ Tutorials - :doc:`../getting_started/step_by_step/scenes_and_nodes` +- `https://github.com/godotengine/godot-demo-projects/ `_ + Properties ---------- @@ -529,6 +531,8 @@ The :ref:`MultiplayerAPI` instance associated with this no The name of the node. This name is unique among the siblings (other child nodes from the same parent). When set to an existing name, the node will be automatically renamed. +**Note:** Auto-generated names might include the ``@`` character, which is reserved for unique names when using :ref:`add_child`. When setting the name manually, any ``@`` will be removed. + ---- .. _class_Node_property_owner: @@ -630,7 +634,7 @@ For gameplay input, :ref:`_unhandled_input` - void **_physics_process** **(** :ref:`float` delta **)** |virtual| -Called during the physics processing step of the main loop. Physics processing means that the frame rate is synced to the physics, i.e. the ``delta`` variable should be constant. +Called during the physics processing step of the main loop. Physics processing means that the frame rate is synced to the physics, i.e. the ``delta`` variable should be constant. ``delta`` is in seconds. It is only called if physics processing is enabled, which is done automatically if this method is overridden, and can be toggled with :ref:`set_physics_process`. @@ -644,7 +648,7 @@ Corresponds to the :ref:`NOTIFICATION_PHYSICS_PROCESS` delta **)** |virtual| -Called during the processing step of the main loop. Processing happens at every frame and as fast as possible, so the ``delta`` time since the previous frame is not constant. +Called during the processing step of the main loop. Processing happens at every frame and as fast as possible, so the ``delta`` time since the previous frame is not constant. ``delta`` is in seconds. It is only called if processing is enabled, which is done automatically if this method is overridden, and can be toggled with :ref:`set_process`. @@ -706,7 +710,7 @@ For gameplay input, this and :ref:`_unhandled_input` first to remove the node from its current parent. For example: @@ -716,7 +720,7 @@ If ``legible_unique_name`` is ``true``, the child node will have an human-readab child_node.get_parent().remove_child(child_node) add_child(child_node) -**Note:** If you want a child to be persisted to a :ref:`PackedScene`, you must set :ref:`owner` in addition to calling :ref:`add_child`. This is typically relevant for `tool scripts `_ and `editor plugins `_. If :ref:`add_child` is called without setting :ref:`owner`, the newly added ``Node`` will not be visible in the scene tree, though it will be visible in the 2D/3D view. +**Note:** If you want a child to be persisted to a :ref:`PackedScene`, you must set :ref:`owner` in addition to calling :ref:`add_child`. This is typically relevant for `tool scripts `_ and `editor plugins `_. If :ref:`add_child` is called without setting :ref:`owner`, the newly added ``Node`` will not be visible in the scene tree, though it will be visible in the 2D/3D view. ---- @@ -726,7 +730,7 @@ If ``legible_unique_name`` is ``true``, the child node will have an human-readab Adds ``child_node`` as a child. The child is placed below the given ``node`` in the list of children. -If ``legible_unique_name`` is ``true``, the child node will have an human-readable name based on the name of the node being instanced instead of its type. +If ``legible_unique_name`` is ``true``, the child node will have a human-readable name based on the name of the node being instanced instead of its type. ---- @@ -922,7 +926,7 @@ Returns the relative :ref:`NodePath` from this node to the speci - :ref:`float` **get_physics_process_delta_time** **(** **)** |const| -Returns the time elapsed since the last physics-bound frame (see :ref:`_physics_process`). This is always a constant value in physics processing unless the frames per second is changed via :ref:`Engine.iterations_per_second`. +Returns the time elapsed (in seconds) since the last physics-bound frame (see :ref:`_physics_process`). This is always a constant value in physics processing unless the frames per second is changed via :ref:`Engine.iterations_per_second`. ---- @@ -1168,7 +1172,7 @@ Queues a node for deletion at the end of the current frame. When deleted, all of - void **raise** **(** **)** -Moves this node to the bottom of parent node's children hierarchy. This is often useful in GUIs (:ref:`Control` nodes), because their order of drawing depends on their order in the tree, i.e. the further they are on the node list, the higher they are drawn. After using ``raise``, a Control will be drawn on top of their siblings. +Moves this node to the bottom of parent node's children hierarchy. This is often useful in GUIs (:ref:`Control` nodes), because their order of drawing depends on their order in the tree. The top Node is drawn first, then any siblings below the top Node in the hierarchy are successively drawn on top of it. After using ``raise``, a Control will be drawn on top of its siblings. ---- @@ -1322,7 +1326,9 @@ Enables or disables physics (i.e. fixed framerate) processing. When a node is be - void **set_physics_process_internal** **(** :ref:`bool` enable **)** -Enables or disables internal physics for this node. Internal physics processing happens in isolation from the normal :ref:`_physics_process` calls and is used by some nodes internally to guarantee proper functioning even if the node is paused or physics processing is disabled for scripting (:ref:`set_physics_process`). Only useful for advanced uses to manipulate built-in nodes' behaviour. +Enables or disables internal physics for this node. Internal physics processing happens in isolation from the normal :ref:`_physics_process` calls and is used by some nodes internally to guarantee proper functioning even if the node is paused or physics processing is disabled for scripting (:ref:`set_physics_process`). Only useful for advanced uses to manipulate built-in nodes' behavior. + +**Warning:** Built-in Nodes rely on the internal processing for their own logic, so changing this value from your code may lead to unexpected behavior. Script access to this internal logic is provided for specific advanced uses, but is unsafe and not supported. ---- @@ -1346,7 +1352,9 @@ Enables or disables input processing. This is not required for GUI controls! Ena - void **set_process_internal** **(** :ref:`bool` enable **)** -Enables or disabled internal processing for this node. Internal processing happens in isolation from the normal :ref:`_process` calls and is used by some nodes internally to guarantee proper functioning even if the node is paused or processing is disabled for scripting (:ref:`set_process`). Only useful for advanced uses to manipulate built-in nodes' behaviour. +Enables or disabled internal processing for this node. Internal processing happens in isolation from the normal :ref:`_process` calls and is used by some nodes internally to guarantee proper functioning even if the node is paused or processing is disabled for scripting (:ref:`set_process`). Only useful for advanced uses to manipulate built-in nodes' behavior. + +**Warning:** Built-in Nodes rely on the internal processing for their own logic, so changing this value from your code may lead to unexpected behavior. Script access to this internal logic is provided for specific advanced uses, but is unsafe and not supported. ---- diff --git a/classes/class_node2d.rst b/classes/class_node2d.rst index 47e2434a2..69f3102e9 100644 --- a/classes/class_node2d.rst +++ b/classes/class_node2d.rst @@ -25,6 +25,8 @@ Tutorials - :doc:`../tutorials/2d/custom_drawing_in_2d` +- `https://github.com/godotengine/godot-demo-projects/tree/master/2d `_ + Properties ---------- diff --git a/classes/class_nodepath.rst b/classes/class_nodepath.rst index 28270be33..5887e250d 100644 --- a/classes/class_nodepath.rst +++ b/classes/class_nodepath.rst @@ -35,6 +35,11 @@ Some examples of NodePaths include the following: @"/root/Main" # If your main scene's root node were named "Main". @"/root/MyAutoload" # If you have an autoloaded node or scene. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/520 `_ + Methods ------- diff --git a/classes/class_noisetexture.rst b/classes/class_noisetexture.rst index 16ef669b0..7f9a3213a 100644 --- a/classes/class_noisetexture.rst +++ b/classes/class_noisetexture.rst @@ -126,6 +126,8 @@ The :ref:`OpenSimplexNoise` instance used to generate th Whether the texture can be tiled without visible seams or not. Seamless textures take longer to generate. +**Note:** Seamless noise has a lower contrast compared to non-seamless noise. This is due to the way noise uses higher dimensions for generating seamless noise. + ---- .. _class_NoiseTexture_property_width: diff --git a/classes/class_object.rst b/classes/class_object.rst index 50dbfa2db..db32cf3af 100644 --- a/classes/class_object.rst +++ b/classes/class_object.rst @@ -11,7 +11,7 @@ Object **Inherited By:** :ref:`ARVRPositionalTracker`, :ref:`ARVRServer`, :ref:`AudioServer`, :ref:`CameraServer`, :ref:`ClassDB`, :ref:`EditorFileSystemDirectory`, :ref:`EditorNavigationMeshGenerator`, :ref:`EditorSelection`, :ref:`EditorVCSInterface`, :ref:`Engine`, :ref:`Geometry`, :ref:`GodotSharp`, :ref:`IP`, :ref:`Input`, :ref:`InputMap`, :ref:`JNISingleton`, :ref:`JSON`, :ref:`JSONRPC`, :ref:`JavaClassWrapper`, :ref:`JavaScript`, :ref:`MainLoop`, :ref:`Marshalls`, :ref:`Node`, :ref:`OS`, :ref:`Performance`, :ref:`Physics2DDirectBodyState`, :ref:`Physics2DDirectSpaceState`, :ref:`Physics2DServer`, :ref:`PhysicsDirectBodyState`, :ref:`PhysicsDirectSpaceState`, :ref:`PhysicsServer`, :ref:`ProjectSettings`, :ref:`Reference`, :ref:`ResourceLoader`, :ref:`ResourceSaver`, :ref:`TranslationServer`, :ref:`TreeItem`, :ref:`UndoRedo`, :ref:`VisualScriptEditor`, :ref:`VisualServer` -Base class for all non built-in types. +Base class for all non-built-in types. Description ----------- @@ -40,11 +40,15 @@ Objects also receive notifications. Notifications are a simple way to notify the **Note:** Unlike references to a :ref:`Reference`, references to an Object stored in a variable can become invalid without warning. Therefore, it's recommended to use :ref:`Reference` for data classes instead of ``Object``. +**Note:** Due to a bug, you can't create a "plain" Object using ``Object.new()``. Instead, use ``ClassDB.instance("Object")``. This bug only applies to Object itself, not any of its descendents like :ref:`Reference`. + Tutorials --------- - :doc:`../getting_started/workflow/best_practices/node_alternatives` +- `#advanced-exports <../getting_started/scripting/gdscript/gdscript_exports.html#advanced-exports>`_ in :doc:`../getting_started/scripting/gdscript/gdscript_exports` + Methods ------- diff --git a/classes/class_omnilight.rst b/classes/class_omnilight.rst index 7e98981a5..137e45f41 100644 --- a/classes/class_omnilight.rst +++ b/classes/class_omnilight.rst @@ -18,6 +18,8 @@ Description An Omnidirectional light is a type of :ref:`Light` that emits light in all directions. The light is attenuated by distance and this attenuation can be configured by changing its energy, radius, and attenuation parameters. +**Note:** By default, only 32 OmniLights may affect a single mesh *resource* at once. Consider splitting your level into several meshes to decrease the likelihood that more than 32 lights will affect the same mesh resource. Splitting the level mesh will also improve frustum culling effectiveness, leading to greater performance. If you need to use more lights per mesh, you can increase :ref:`ProjectSettings.rendering/limits/rendering/max_lights_per_object` at the cost of shader compilation times. + Tutorials --------- diff --git a/classes/class_opensimplexnoise.rst b/classes/class_opensimplexnoise.rst index a972caa90..bd1eff214 100644 --- a/classes/class_opensimplexnoise.rst +++ b/classes/class_opensimplexnoise.rst @@ -52,23 +52,23 @@ Properties Methods ------- -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Image` | :ref:`get_image` **(** :ref:`int` width, :ref:`int` height **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_noise_1d` **(** :ref:`float` x **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_noise_2d` **(** :ref:`float` x, :ref:`float` y **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_noise_2dv` **(** :ref:`Vector2` pos **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_noise_3d` **(** :ref:`float` x, :ref:`float` y, :ref:`float` z **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_noise_3dv` **(** :ref:`Vector3` pos **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_noise_4d` **(** :ref:`float` x, :ref:`float` y, :ref:`float` z, :ref:`float` w **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Image` | :ref:`get_seamless_image` **(** :ref:`int` size **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Image` | :ref:`get_image` **(** :ref:`int` width, :ref:`int` height **)** |const| | ++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`get_noise_1d` **(** :ref:`float` x **)** |const| | ++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`get_noise_2d` **(** :ref:`float` x, :ref:`float` y **)** |const| | ++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`get_noise_2dv` **(** :ref:`Vector2` pos **)** |const| | ++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`get_noise_3d` **(** :ref:`float` x, :ref:`float` y, :ref:`float` z **)** |const| | ++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`get_noise_3dv` **(** :ref:`Vector3` pos **)** |const| | ++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`get_noise_4d` **(** :ref:`float` x, :ref:`float` y, :ref:`float` z, :ref:`float` w **)** |const| | ++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Image` | :ref:`get_seamless_image` **(** :ref:`int` size **)** |const| | ++---------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Property Descriptions --------------------- @@ -158,15 +158,15 @@ Method Descriptions .. _class_OpenSimplexNoise_method_get_image: -- :ref:`Image` **get_image** **(** :ref:`int` width, :ref:`int` height **)** +- :ref:`Image` **get_image** **(** :ref:`int` width, :ref:`int` height **)** |const| -Generate a noise image with the requested ``width`` and ``height``, based on the current noise parameters. +Generate a noise image in :ref:`Image.FORMAT_L8` format with the requested ``width`` and ``height``, based on the current noise parameters. ---- .. _class_OpenSimplexNoise_method_get_noise_1d: -- :ref:`float` **get_noise_1d** **(** :ref:`float` x **)** +- :ref:`float` **get_noise_1d** **(** :ref:`float` x **)** |const| Returns the 1D noise value ``[-1,1]`` at the given x-coordinate. @@ -176,7 +176,7 @@ Returns the 1D noise value ``[-1,1]`` at the given x-coordinate. .. _class_OpenSimplexNoise_method_get_noise_2d: -- :ref:`float` **get_noise_2d** **(** :ref:`float` x, :ref:`float` y **)** +- :ref:`float` **get_noise_2d** **(** :ref:`float` x, :ref:`float` y **)** |const| Returns the 2D noise value ``[-1,1]`` at the given position. @@ -184,7 +184,7 @@ Returns the 2D noise value ``[-1,1]`` at the given position. .. _class_OpenSimplexNoise_method_get_noise_2dv: -- :ref:`float` **get_noise_2dv** **(** :ref:`Vector2` pos **)** +- :ref:`float` **get_noise_2dv** **(** :ref:`Vector2` pos **)** |const| Returns the 2D noise value ``[-1,1]`` at the given position. @@ -192,7 +192,7 @@ Returns the 2D noise value ``[-1,1]`` at the given position. .. _class_OpenSimplexNoise_method_get_noise_3d: -- :ref:`float` **get_noise_3d** **(** :ref:`float` x, :ref:`float` y, :ref:`float` z **)** +- :ref:`float` **get_noise_3d** **(** :ref:`float` x, :ref:`float` y, :ref:`float` z **)** |const| Returns the 3D noise value ``[-1,1]`` at the given position. @@ -200,7 +200,7 @@ Returns the 3D noise value ``[-1,1]`` at the given position. .. _class_OpenSimplexNoise_method_get_noise_3dv: -- :ref:`float` **get_noise_3dv** **(** :ref:`Vector3` pos **)** +- :ref:`float` **get_noise_3dv** **(** :ref:`Vector3` pos **)** |const| Returns the 3D noise value ``[-1,1]`` at the given position. @@ -208,7 +208,7 @@ Returns the 3D noise value ``[-1,1]`` at the given position. .. _class_OpenSimplexNoise_method_get_noise_4d: -- :ref:`float` **get_noise_4d** **(** :ref:`float` x, :ref:`float` y, :ref:`float` z, :ref:`float` w **)** +- :ref:`float` **get_noise_4d** **(** :ref:`float` x, :ref:`float` y, :ref:`float` z, :ref:`float` w **)** |const| Returns the 4D noise value ``[-1,1]`` at the given position. @@ -216,9 +216,11 @@ Returns the 4D noise value ``[-1,1]`` at the given position. .. _class_OpenSimplexNoise_method_get_seamless_image: -- :ref:`Image` **get_seamless_image** **(** :ref:`int` size **)** +- :ref:`Image` **get_seamless_image** **(** :ref:`int` size **)** |const| -Generate a tileable noise image, based on the current noise parameters. Generated seamless images are always square (``size`` × ``size``). +Generate a tileable noise image in :ref:`Image.FORMAT_L8` format, based on the current noise parameters. Generated seamless images are always square (``size`` × ``size``). + +**Note:** Seamless noise has a lower contrast compared to non-seamless noise. This is due to the way noise uses higher dimensions for generating seamless noise. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_optionbutton.rst b/classes/class_optionbutton.rst index 803280549..95d434f4a 100644 --- a/classes/class_optionbutton.rst +++ b/classes/class_optionbutton.rst @@ -18,6 +18,8 @@ Description OptionButton is a type button that provides a selectable list of items when pressed. The item selected becomes the "current" item and is displayed as the button text. +See also :ref:`BaseButton` which contains common properties and methods associated with this node. + Properties ---------- diff --git a/classes/class_os.rst b/classes/class_os.rst index 305ccc298..014de9b00 100644 --- a/classes/class_os.rst +++ b/classes/class_os.rst @@ -18,6 +18,11 @@ Description Operating System functions. OS wraps the most common functionality to communicate with the host operating system, such as the clipboard, video driver, date and time, timers, environment variables, execution of binaries, command line, etc. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/677 `_ + Properties ---------- @@ -107,7 +112,7 @@ Methods +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_dynamic_memory_usage` **(** **)** |const| | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_environment` **(** :ref:`String` environment **)** |const| | +| :ref:`String` | :ref:`get_environment` **(** :ref:`String` variable **)** |const| | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_executable_path` **(** **)** |const| | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -125,6 +130,8 @@ Methods +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_name` **(** **)** |const| | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_native_handle` **(** :ref:`HandleType` handle_type **)** | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_power_percent_left` **(** **)** | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_power_seconds_left` **(** **)** | @@ -167,6 +174,8 @@ Methods +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_tablet_driver_name` **(** :ref:`int` idx **)** |const| | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_thread_caller_id` **(** **)** |const| | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_ticks_msec` **(** **)** |const| | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_ticks_usec` **(** **)** |const| | @@ -199,7 +208,7 @@ Methods +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`global_menu_remove_item` **(** :ref:`String` menu, :ref:`int` idx **)** | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_environment` **(** :ref:`String` environment **)** |const| | +| :ref:`bool` | :ref:`has_environment` **(** :ref:`String` variable **)** |const| | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_feature` **(** :ref:`String` tag_name **)** |const| | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -263,6 +272,8 @@ Methods +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`request_permissions` **(** **)** | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`set_environment` **(** :ref:`String` variable, :ref:`String` value **)** |const| | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_icon` **(** :ref:`Image` icon **)** | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_ime_active` **(** :ref:`bool` active **)** | @@ -277,6 +288,8 @@ Methods +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_window_always_on_top` **(** :ref:`bool` enabled **)** | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_window_mouse_passthrough` **(** :ref:`PoolVector2Array` region **)** | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_window_title` **(** :ref:`String` title **)** | +-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`shell_open` **(** :ref:`String` uri **)** | @@ -389,6 +402,58 @@ enum **Month**: ---- +.. _enum_OS_HandleType: + +.. _class_OS_constant_APPLICATION_HANDLE: + +.. _class_OS_constant_DISPLAY_HANDLE: + +.. _class_OS_constant_WINDOW_HANDLE: + +.. _class_OS_constant_WINDOW_VIEW: + +.. _class_OS_constant_OPENGL_CONTEXT: + +enum **HandleType**: + +- **APPLICATION_HANDLE** = **0** --- Application handle: + +- Windows: ``HINSTANCE`` of the application + +- MacOS: ``NSApplication*`` of the application (not yet implemented) + +- Android: ``JNIEnv*`` of the application (not yet implemented) + +- **DISPLAY_HANDLE** = **1** --- Display handle: + +- Linux: ``X11::Display*`` for the display + +- **WINDOW_HANDLE** = **2** --- Window handle: + +- Windows: ``HWND`` of the main window + +- Linux: ``X11::Window*`` of the main window + +- MacOS: ``NSWindow*`` of the main window (not yet implemented) + +- Android: ``jObject`` the main android activity (not yet implemented) + +- **WINDOW_VIEW** = **3** --- Window view: + +- Windows: ``HDC`` of the main window drawing context + +- MacOS: ``NSView*`` of the main windows view (not yet implemented) + +- **OPENGL_CONTEXT** = **4** --- OpenGL Context: + +- Windows: ``HGLRC`` + +- Linux: ``X11::GLXContext`` + +- MacOS: ``NSOpenGLContext*`` (not yet implemented) + +---- + .. _enum_OS_ScreenOrientation: .. _class_OS_constant_SCREEN_ORIENTATION_LANDSCAPE: @@ -646,7 +711,7 @@ The current screen orientation. | *Getter* | get_current_tablet_driver() | +-----------+----------------------------------+ -The current tablet drvier in use. +The current tablet driver in use. ---- @@ -869,7 +934,7 @@ Shuts down system MIDI driver. - void **delay_msec** **(** :ref:`int` msec **)** |const| -Delay execution of the current thread by ``msec`` milliseconds. +Delay execution of the current thread by ``msec`` milliseconds. ``usec`` must be greater than or equal to ``0``. Otherwise, :ref:`delay_msec` will do nothing and will print an error message. ---- @@ -877,7 +942,7 @@ Delay execution of the current thread by ``msec`` milliseconds. - void **delay_usec** **(** :ref:`int` usec **)** |const| -Delay execution of the current thread by ``usec`` microseconds. +Delay execution of the current thread by ``usec`` microseconds. ``usec`` must be greater than or equal to ``0``. Otherwise, :ref:`delay_usec` will do nothing and will print an error message. ---- @@ -1046,9 +1111,11 @@ Returns the total amount of dynamic memory used (only works in debug). .. _class_OS_method_get_environment: -- :ref:`String` **get_environment** **(** :ref:`String` environment **)** |const| +- :ref:`String` **get_environment** **(** :ref:`String` variable **)** |const| -Returns an environment variable. +Returns the value of an environment variable. Returns an empty string if the environment variable doesn't exist. + +**Note:** Double-check the casing of ``variable``. Environment variable names are case-sensitive on all platforms except Windows. ---- @@ -1132,6 +1199,16 @@ Returns the name of the host OS. Possible values are: ``"Android"``, ``"iOS"``, ---- +.. _class_OS_method_get_native_handle: + +- :ref:`int` **get_native_handle** **(** :ref:`HandleType` handle_type **)** + +Returns internal structure pointers for use in GDNative plugins. + +**Note:** This method is implemented on Linux and Windows (other OSs will soon be supported). + +---- + .. _class_OS_method_get_power_percent_left: - :ref:`int` **get_power_percent_left** **(** **)** @@ -1212,7 +1289,9 @@ Returns the number of displays attached to the host machine. Returns the dots per inch density of the specified screen. If ``screen`` is ``-1`` (the default value), the current screen will be used. -On Android devices, the actual screen densities are grouped into six generalized densities: +**Note:** On macOS, returned value is inaccurate if fractional display scaling mode is used. + +**Note:** On Android devices, the actual screen densities are grouped into six generalized densities: :: @@ -1337,6 +1416,16 @@ Returns the tablet driver name for the given index. ---- +.. _class_OS_method_get_thread_caller_id: + +- :ref:`int` **get_thread_caller_id** **(** **)** |const| + +Returns the ID of the current thread. This can be used in logs to ease debugging of multi-threaded applications. + +**Note:** Thread IDs are not deterministic and may be reused across application restarts. + +---- + .. _class_OS_method_get_ticks_msec: - :ref:`int` **get_ticks_msec** **(** **)** |const| @@ -1383,7 +1472,9 @@ Returns a string that is unique to the device. - :ref:`int` **get_unix_time** **(** **)** |const| -Returns the current UNIX epoch timestamp. +Returns the current UNIX epoch timestamp in seconds. + +**Important:** This is the system clock that the user can manully set. **Never use** this method for precise time calculation since its results are also subject to automatic adjustments by the operating system. **Always use** :ref:`get_ticks_usec` or :ref:`get_ticks_msec` for precise time calculation instead, since they are guaranteed to be monotonic (i.e. never decrease). ---- @@ -1395,6 +1486,8 @@ Gets an epoch time value from a dictionary of time values. ``datetime`` must be populated with the following keys: ``year``, ``month``, ``day``, ``hour``, ``minute``, ``second``. +If the dictionary is empty ``0`` is returned. + You can pass the output from :ref:`get_datetime_from_unix_time` directly into this function. Daylight Savings Time (``dst``), if present, is ignored. ---- @@ -1489,9 +1582,11 @@ Removes the item at index "idx" from the global menu. Note that the indexes of i .. _class_OS_method_has_environment: -- :ref:`bool` **has_environment** **(** :ref:`String` environment **)** |const| +- :ref:`bool` **has_environment** **(** :ref:`String` variable **)** |const| -Returns ``true`` if an environment variable exists. +Returns ``true`` if the environment variable with the name ``variable`` exists. + +**Note:** Double-check the casing of ``variable``. Environment variable names are case-sensitive on all platforms except Windows. ---- @@ -1499,7 +1594,7 @@ Returns ``true`` if an environment variable exists. - :ref:`bool` **has_feature** **(** :ref:`String` tag_name **)** |const| -Returns ``true`` if the feature for the given feature tag is supported in the currently running instance, depending on platform, build etc. Can be used to check whether you're currently running a debug build, on a certain platform or arch, etc. Refer to the `Feature Tags `_ documentation for more details. +Returns ``true`` if the feature for the given feature tag is supported in the currently running instance, depending on platform, build etc. Can be used to check whether you're currently running a debug build, on a certain platform or arch, etc. Refer to the `Feature Tags `_ documentation for more details. **Note:** Tag names are case-sensitive. @@ -1783,6 +1878,16 @@ With this function you can request dangerous permissions since normal permission ---- +.. _class_OS_method_set_environment: + +- :ref:`bool` **set_environment** **(** :ref:`String` variable, :ref:`String` value **)** |const| + +Sets the value of the environment variable ``variable`` to ``value``. The environment variable will be set for the Godot process and any process executed with :ref:`execute` after running :ref:`set_environment`. The environment variable will *not* persist to processes run after the Godot process was terminated. + +**Note:** Double-check the casing of ``variable``. Environment variable names are case-sensitive on all platforms except Windows. + +---- + .. _class_OS_method_set_icon: - void **set_icon** **(** :ref:`Image` icon **)** @@ -1859,6 +1964,31 @@ Sets whether the window should always be on top. ---- +.. _class_OS_method_set_window_mouse_passthrough: + +- void **set_window_mouse_passthrough** **(** :ref:`PoolVector2Array` region **)** + +Sets a polygonal region of the window which accepts mouse events. Mouse events outside the region will be passed through. + +Passing an empty array will disable passthrough support (all mouse events will be intercepted by the window, which is the default behavior). + +:: + + # Set region, using Path2D node. + OS.set_window_mouse_passthrough($Path2D.curve.get_baked_points()) + + # Set region, using Polygon2D node. + OS.set_window_mouse_passthrough($Polygon2D.polygon) + + # Reset region to default. + OS.set_window_mouse_passthrough([]) + +**Note:** On Windows, the portion of a window that lies outside the region is not drawn, while on Linux and macOS it is. + +**Note:** This method is implemented on Linux, macOS and Windows. + +---- + .. _class_OS_method_set_window_title: - void **set_window_title** **(** :ref:`String` title **)** diff --git a/classes/class_packedscene.rst b/classes/class_packedscene.rst index 0ac670d2b..6f99db551 100644 --- a/classes/class_packedscene.rst +++ b/classes/class_packedscene.rst @@ -18,7 +18,7 @@ Description A simplified interface to a scene file. Provides access to operations and checks that can be performed on the scene resource itself. -Can be used to save a node to a file. When saving, the node as well as all the node it owns get saved (see ``owner`` property on :ref:`Node`). +Can be used to save a node to a file. When saving, the node as well as all the nodes it owns get saved (see ``owner`` property on :ref:`Node`). **Note:** The node doesn't need to own itself. @@ -55,6 +55,11 @@ Can be used to save a node to a file. When saving, the node as well as all the n if error != OK: push_error("An error occurred while saving the scene to disk.") +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/520 `_ + Properties ---------- diff --git a/classes/class_packetpeerudp.rst b/classes/class_packetpeerudp.rst index d1136d72a..cd1001336 100644 --- a/classes/class_packetpeerudp.rst +++ b/classes/class_packetpeerudp.rst @@ -64,7 +64,7 @@ Closes the UDP socket the ``PacketPeerUDP`` is currently listening on. Calling this method connects this UDP peer to the given ``host``/``port`` pair. UDP is in reality connectionless, so this option only means that incoming packets from different addresses are automatically discarded, and that outgoing packets are always sent to the connected address (future calls to :ref:`set_dest_address` are not allowed). This method does not send any data to the remote peer, to do that, use :ref:`PacketPeer.put_var` or :ref:`PacketPeer.put_packet` as usual. See also :ref:`UDPServer`. -Note: Connecting to the remote peer does not help to protect from malicious attacks like IP spoofing, etc. Think about using an encryption technique like SSL or DTLS if you feel like your application is transfering sensitive information. +**Note:** Connecting to the remote peer does not help to protect from malicious attacks like IP spoofing, etc. Think about using an encryption technique like SSL or DTLS if you feel like your application is transferring sensitive information. ---- @@ -160,6 +160,20 @@ Note: :ref:`set_broadcast_enabled`. +**Note:** :ref:`wait` can't be interrupted once it has been called. This can be worked around by allowing the other party to send a specific "death pill" packet like this: + +:: + + # Server + socket.set_dest_address("127.0.0.1", 789) + socket.put_packet("Time to stop".to_ascii()) + + # Client + while socket.wait() == OK: + var data = socket.get_packet().get_string_from_ascii() + if data == "Time to stop": + return + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_panel.rst b/classes/class_panel.rst index 7102b7e87..9d66aca45 100644 --- a/classes/class_panel.rst +++ b/classes/class_panel.rst @@ -18,6 +18,15 @@ Description Panel is a :ref:`Control` that displays an opaque background. It's commonly used as a parent and container for other types of :ref:`Control` nodes. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/520 `_ + +- `https://godotengine.org/asset-library/asset/516 `_ + +- `https://godotengine.org/asset-library/asset/523 `_ + Theme Properties ---------------- diff --git a/classes/class_panelcontainer.rst b/classes/class_panelcontainer.rst index 4dcd081b7..dfac265b5 100644 --- a/classes/class_panelcontainer.rst +++ b/classes/class_panelcontainer.rst @@ -20,6 +20,11 @@ Description Panel container type. This container fits controls inside of the delimited area of a stylebox. It's useful for giving controls an outline. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/520 `_ + Theme Properties ---------------- diff --git a/classes/class_particles.rst b/classes/class_particles.rst index 0f3742c17..d62b02051 100644 --- a/classes/class_particles.rst +++ b/classes/class_particles.rst @@ -11,7 +11,7 @@ Particles **Inherits:** :ref:`GeometryInstance` **<** :ref:`VisualInstance` **<** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` -3D particle emitter. +GPU-based 3D particle emitter. Description ----------- @@ -20,11 +20,17 @@ Description Use the ``process_material`` property to add a :ref:`ParticlesMaterial` to configure particle appearance and behavior. Alternatively, you can add a :ref:`ShaderMaterial` which will be applied to all particles. +**Note:** ``Particles`` only work when using the GLES3 renderer. If using the GLES2 renderer, use :ref:`CPUParticles` instead. You can convert ``Particles`` to :ref:`CPUParticles` by selecting the node, clicking the **Particles** menu at the top of the 3D editor viewport then choosing **Convert to CPUParticles**. + +**Note:** After working on a Particles node, remember to update its :ref:`visibility_aabb` by selecting it, clicking the **Particles** menu at the top of the 3D editor viewport then choose **Generate Visibility AABB**. Otherwise, particles may suddenly disappear depending on the camera position and angle. + Tutorials --------- - :doc:`../tutorials/3d/vertex_animation/controlling_thousands_of_fish` +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- @@ -122,7 +128,9 @@ Property Descriptions | *Getter* | get_amount() | +-----------+-------------------+ -Number of particles to emit. +The number of particles emitted in one emission cycle (corresponding to the :ref:`lifetime`). + +**Note:** Changing :ref:`amount` will reset the particle emission, therefore removing all particles that were already emitted before changing :ref:`amount`. ---- @@ -290,7 +298,7 @@ If ``true``, results in fractional delta calculation which has a smoother partic | *Getter* | get_lifetime() | +-----------+---------------------+ -Amount of time each particle will exist. +The amount of time each particle will exist (in seconds). ---- @@ -400,7 +408,9 @@ Speed scaling ratio. A value of ``0`` can be used to pause the particles. | *Getter* | get_visibility_aabb() | +-----------+---------------------------------+ -The :ref:`AABB` that determines the area of the world part of which needs to be visible on screen for the particle system to be active. +The :ref:`AABB` that determines the node's region which needs to be visible on screen for the particle system to be active. + +Grow the box if particles suddenly appear/disappear when the node enters/exits the screen. The :ref:`AABB` can be grown via code or with the **Particles → Generate AABB** editor tool. **Note:** If the :ref:`ParticlesMaterial` in use is configured to cast shadows, you may want to enlarge this AABB to ensure the shadow is updated when particles are off-screen. diff --git a/classes/class_particles2d.rst b/classes/class_particles2d.rst index afb3fdb85..e1f3d5001 100644 --- a/classes/class_particles2d.rst +++ b/classes/class_particles2d.rst @@ -11,7 +11,7 @@ Particles2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -2D particle emitter. +GPU-based 2D particle emitter. Description ----------- @@ -20,11 +20,19 @@ Description Use the ``process_material`` property to add a :ref:`ParticlesMaterial` to configure particle appearance and behavior. Alternatively, you can add a :ref:`ShaderMaterial` which will be applied to all particles. +**Note:** ``Particles2D`` only work when using the GLES3 renderer. If using the GLES2 renderer, use :ref:`CPUParticles2D` instead. You can convert ``Particles2D`` to :ref:`CPUParticles2D` by selecting the node, clicking the **Particles** menu at the top of the 2D editor viewport then choosing **Convert to CPUParticles2D**. + +**Note:** After working on a Particles node, remember to update its :ref:`visibility_rect` by selecting it, clicking the **Particles** menu at the top of the 2D editor viewport then choose **Generate Visibility Rect**. Otherwise, particles may suddenly disappear depending on the camera position and angle. + +**Note:** Unlike :ref:`CPUParticles2D`, ``Particles2D`` currently ignore the texture region defined in :ref:`AtlasTexture`\ s. + Tutorials --------- - :doc:`../tutorials/2d/particle_systems_2d` +- `https://godotengine.org/asset-library/asset/515 `_ + Properties ---------- @@ -101,7 +109,9 @@ Property Descriptions | *Getter* | get_amount() | +-----------+-------------------+ -Number of particles emitted in one emission cycle. +The number of particles emitted in one emission cycle (corresponding to the :ref:`lifetime`). + +**Note:** Changing :ref:`amount` will reset the particle emission, therefore removing all particles that were already emitted before changing :ref:`amount`. ---- @@ -197,7 +207,7 @@ If ``true``, results in fractional delta calculation which has a smoother partic | *Getter* | get_lifetime() | +-----------+---------------------+ -Amount of time each particle will exist. +The amount of time each particle will exist (in seconds). ---- @@ -337,7 +347,9 @@ Particle texture. If ``null``, particles will be squares. | *Getter* | get_visibility_rect() | +-----------+-----------------------------------+ -Editor visibility helper. +The :ref:`Rect2` that determines the node's region which needs to be visible on screen for the particle system to be active. + +Grow the rect if particles suddenly appear/disappear when the node enters/exits the screen. The :ref:`Rect2` can be grown via code or with the **Particles → Generate Visibility Rect** editor tool. Method Descriptions ------------------- diff --git a/classes/class_physics2ddirectspacestate.rst b/classes/class_physics2ddirectspacestate.rst index 8a80fa6e2..33b31260d 100644 --- a/classes/class_physics2ddirectspacestate.rst +++ b/classes/class_physics2ddirectspacestate.rst @@ -49,9 +49,11 @@ Method Descriptions - :ref:`Array` **cast_motion** **(** :ref:`Physics2DShapeQueryParameters` shape **)** -Checks how far the shape can travel toward a point. If the shape can not move, the array will be empty. +Checks how far a :ref:`Shape2D` can move without colliding. All the parameters for the query, including the shape and the motion, are supplied through a :ref:`Physics2DShapeQueryParameters` object. -**Note:** Both the shape and the motion are supplied through a :ref:`Physics2DShapeQueryParameters` object. The method will return an array with two floats between 0 and 1, both representing a fraction of ``motion``. The first is how far the shape can move without triggering a collision, and the second is the point at which a collision will occur. If no collision is detected, the returned array will be ``[1, 1]``. +Returns an array with the safe and unsafe proportions (between 0 and 1) of the motion. The safe proportion is the maximum fraction of the motion that can be made without a collision. The unsafe proportion is the minimum fraction of the distance that must be moved for a collision. If no collision is detected a result of ``[1.0, 1.0]`` will be returned. + +**Note:** Any :ref:`Shape2D`\ s that the shape is already colliding with e.g. inside of, will be ignored. Use :ref:`collide_shape` to determine the :ref:`Shape2D`\ s that the shape is already colliding with. ---- @@ -91,7 +93,7 @@ Checks the intersections of a shape, given through a :ref:`Physics2DShapeQueryPa - :ref:`Array` **intersect_point** **(** :ref:`Vector2` point, :ref:`int` max_results=32, :ref:`Array` exclude=[ ], :ref:`int` collision_layer=2147483647, :ref:`bool` collide_with_bodies=true, :ref:`bool` collide_with_areas=false **)** -Checks whether a point is inside any shape. The shapes the point is inside of are returned in an array containing dictionaries with the following fields: +Checks whether a point is inside any solid shape. The shapes the point is inside of are returned in an array containing dictionaries with the following fields: ``collider``: The colliding object. @@ -105,6 +107,8 @@ Checks whether a point is inside any shape. The shapes the point is inside of ar Additionally, the method can take an ``exclude`` array of objects or :ref:`RID`\ s that are to be excluded from collisions, a ``collision_mask`` bitmask representing the physics layers to check in, or booleans to determine if the ray should collide with :ref:`PhysicsBody`\ s or :ref:`Area`\ s, respectively. +**Note:** :ref:`ConcavePolygonShape2D`\ s and :ref:`CollisionPolygon2D`\ s in ``Segments`` build mode are not solid shapes. Therefore, they will not be detected. + ---- .. _class_Physics2DDirectSpaceState_method_intersect_point_on_canvas: diff --git a/classes/class_physics2dserver.rst b/classes/class_physics2dserver.rst index ca365e4da..9a4fa2329 100644 --- a/classes/class_physics2dserver.rst +++ b/classes/class_physics2dserver.rst @@ -599,7 +599,7 @@ Removes all shapes from an area. It does not delete the shapes, so they can be r - :ref:`RID` **area_create** **(** **)** -Creates an :ref:`Area2D`. +Creates an :ref:`Area2D`. After creating an :ref:`Area2D` with this method, assign it to a space using :ref:`area_set_space` to use the created :ref:`Area2D` in the physics world. ---- diff --git a/classes/class_physics2dshapequeryparameters.rst b/classes/class_physics2dshapequeryparameters.rst index 7168a4c34..fcb91ea0b 100644 --- a/classes/class_physics2dshapequeryparameters.rst +++ b/classes/class_physics2dshapequeryparameters.rst @@ -93,7 +93,7 @@ If ``true``, the query will take :ref:`PhysicsBody2D`\ s in | *Getter* | get_collision_layer() | +-----------+----------------------------+ -The physics layer(s) the query will take into account (as a bitmask). See `Collision layers and masks `_ in the documentation for more information. +The physics layer(s) the query will take into account (as a bitmask). See `Collision layers and masks `_ in the documentation for more information. ---- diff --git a/classes/class_physicsbody.rst b/classes/class_physicsbody.rst index c846c5a17..b4d69f453 100644 --- a/classes/class_physicsbody.rst +++ b/classes/class_physicsbody.rst @@ -72,7 +72,7 @@ The physics layers this area is in. Collidable objects can exist in any of 32 different layers. These layers work like a tagging system, and are not visual. A collidable can use these layers to select with which objects it can collide, using the :ref:`collision_mask` property. -A contact is detected if object A is in any of the layers that object B scans, or object B is in any layer scanned by object A. See `Collision layers and masks `_ in the documentation for more information. +A contact is detected if object A is in any of the layers that object B scans, or object B is in any layer scanned by object A. See `Collision layers and masks `_ in the documentation for more information. ---- @@ -88,7 +88,7 @@ A contact is detected if object A is in any of the layers that object B scans, o | *Getter* | get_collision_mask() | +-----------+---------------------------+ -The physics layers this area scans for collisions. See `Collision layers and masks `_ in the documentation for more information. +The physics layers this area scans for collisions. See `Collision layers and masks `_ in the documentation for more information. Method Descriptions ------------------- diff --git a/classes/class_physicsbody2d.rst b/classes/class_physicsbody2d.rst index 1622af8f2..53f0e701f 100644 --- a/classes/class_physicsbody2d.rst +++ b/classes/class_physicsbody2d.rst @@ -76,7 +76,7 @@ The physics layers this area is in. Collidable objects can exist in any of 32 different layers. These layers work like a tagging system, and are not visual. A collidable can use these layers to select with which objects it can collide, using the :ref:`collision_mask` property. -A contact is detected if object A is in any of the layers that object B scans, or object B is in any layer scanned by object A. See `Collision layers and masks `_ in the documentation for more information. +A contact is detected if object A is in any of the layers that object B scans, or object B is in any layer scanned by object A. See `Collision layers and masks `_ in the documentation for more information. ---- @@ -92,7 +92,7 @@ A contact is detected if object A is in any of the layers that object B scans, o | *Getter* | get_collision_mask() | +-----------+---------------------------+ -The physics layers this area scans for collisions. See `Collision layers and masks `_ in the documentation for more information. +The physics layers this area scans for collisions. See `Collision layers and masks `_ in the documentation for more information. ---- diff --git a/classes/class_physicsdirectspacestate.rst b/classes/class_physicsdirectspacestate.rst index 29eb46b2d..614e47e54 100644 --- a/classes/class_physicsdirectspacestate.rst +++ b/classes/class_physicsdirectspacestate.rst @@ -45,9 +45,11 @@ Method Descriptions - :ref:`Array` **cast_motion** **(** :ref:`PhysicsShapeQueryParameters` shape, :ref:`Vector3` motion **)** -Checks whether the shape can travel to a point. The method will return an array with two floats between 0 and 1, both representing a fraction of ``motion``. The first is how far the shape can move without triggering a collision, and the second is the point at which a collision will occur. If no collision is detected, the returned array will be ``[1, 1]``. +Checks how far a :ref:`Shape` can move without colliding. All the parameters for the query, including the shape, are supplied through a :ref:`PhysicsShapeQueryParameters` object. -If the shape can not move, the returned array will be ``[0, 0]`` under Bullet, and empty under GodotPhysics. +Returns an array with the safe and unsafe proportions (between 0 and 1) of the motion. The safe proportion is the maximum fraction of the motion that can be made without a collision. The unsafe proportion is the minimum fraction of the distance that must be moved for a collision. If no collision is detected a result of ``[1.0, 1.0]`` will be returned. + +**Note:** Any :ref:`Shape`\ s that the shape is already colliding with e.g. inside of, will be ignored. Use :ref:`collide_shape` to determine the :ref:`Shape`\ s that the shape is already colliding with. ---- diff --git a/classes/class_physicsserver.rst b/classes/class_physicsserver.rst index f04e5c7ab..7b144ebe0 100644 --- a/classes/class_physicsserver.rst +++ b/classes/class_physicsserver.rst @@ -468,7 +468,7 @@ enum **ConeTwistJointParam**: - **CONE_TWIST_JOINT_SWING_SPAN** = **0** --- Swing is rotation from side to side, around the axis perpendicular to the twist axis. -The swing span defines, how much rotation will not get corrected allong the swing axis. +The swing span defines, how much rotation will not get corrected along the swing axis. Could be defined as looseness in the :ref:`ConeTwistJoint`. diff --git a/classes/class_physicsshapequeryparameters.rst b/classes/class_physicsshapequeryparameters.rst index 52915dd59..62df47d1c 100644 --- a/classes/class_physicsshapequeryparameters.rst +++ b/classes/class_physicsshapequeryparameters.rst @@ -91,7 +91,7 @@ If ``true``, the query will take :ref:`PhysicsBody`\ s into a | *Getter* | get_collision_mask() | +-----------+---------------------------+ -The physics layer(s) the query will take into account (as a bitmask). See `Collision layers and masks `_ in the documentation for more information. +The physics layer(s) the query will take into account (as a bitmask). See `Collision layers and masks `_ in the documentation for more information. ---- diff --git a/classes/class_pinjoint.rst b/classes/class_pinjoint.rst index 06f794ed7..8bd50035c 100644 --- a/classes/class_pinjoint.rst +++ b/classes/class_pinjoint.rst @@ -11,12 +11,12 @@ PinJoint **Inherits:** :ref:`Joint` **<** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` -Pin joint for 3D shapes. +Pin joint for 3D PhysicsBodies. Description ----------- -Pin joint for 3D rigid bodies. It pins 2 bodies (rigid or static) together. +Pin joint for 3D rigid bodies. It pins 2 bodies (rigid or static) together. See also :ref:`Generic6DOFJoint`. Properties ---------- diff --git a/classes/class_planemesh.rst b/classes/class_planemesh.rst index ca376ea5b..d411523f2 100644 --- a/classes/class_planemesh.rst +++ b/classes/class_planemesh.rst @@ -18,6 +18,8 @@ Description Class representing a planar :ref:`PrimitiveMesh`. This flat mesh does not have a thickness. By default, this mesh is aligned on the X and Z axes; this default rotation isn't suited for use with billboarded materials. For billboarded materials, use :ref:`QuadMesh` instead. +**Note:** When using a large textured ``PlaneMesh`` (e.g. as a floor), you may stumble upon UV jittering issues depending on the camera angle. To solve this, increase :ref:`subdivide_depth` and :ref:`subdivide_width` until you no longer notice UV jittering. + Properties ---------- diff --git a/classes/class_poolrealarray.rst b/classes/class_poolrealarray.rst index c42ee95d9..aa31f5a7d 100644 --- a/classes/class_poolrealarray.rst +++ b/classes/class_poolrealarray.rst @@ -14,10 +14,12 @@ A pooled :ref:`Array` of reals (:ref:`float`). Description ----------- -An :ref:`Array` specifically designed to hold floating-point values (:ref:`float`). Optimized for memory usage, does not fragment the memory. +An :ref:`Array` specifically designed to hold floating-point values. Optimized for memory usage, does not fragment the memory. **Note:** This type is passed by value and not by reference. +**Note:** Unlike primitive :ref:`float`\ s which are 64-bit, numbers stored in ``PoolRealArray`` are 32-bit floats. This means values stored in ``PoolRealArray`` have lower precision compared to primitive :ref:`float`\ s. If you need to store 64-bit floats in an array, use a generic :ref:`Array` with :ref:`float` elements as these will still be 64-bit. However, using a generic :ref:`Array` to store :ref:`float`\ s will use roughly 6 times more memory compared to a ``PoolRealArray``. + Methods ------- diff --git a/classes/class_poolstringarray.rst b/classes/class_poolstringarray.rst index 7a0bdb070..bdb11b57e 100644 --- a/classes/class_poolstringarray.rst +++ b/classes/class_poolstringarray.rst @@ -18,6 +18,11 @@ An :ref:`Array` specifically designed to hold :ref:`String`_ + Methods ------- diff --git a/classes/class_poolvector2array.rst b/classes/class_poolvector2array.rst index 6f3097f80..8b93e8a0c 100644 --- a/classes/class_poolvector2array.rst +++ b/classes/class_poolvector2array.rst @@ -18,6 +18,11 @@ An :ref:`Array` specifically designed to hold :ref:`Vector2`_ + Methods ------- diff --git a/classes/class_popupmenu.rst b/classes/class_popupmenu.rst index 6747b1b9e..15b12a229 100644 --- a/classes/class_popupmenu.rst +++ b/classes/class_popupmenu.rst @@ -63,7 +63,7 @@ Methods +---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_radio_check_shortcut` **(** :ref:`ShortCut` shortcut, :ref:`int` id=-1, :ref:`bool` global=false **)** | +---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_separator` **(** :ref:`String` label="" **)** | +| void | :ref:`add_separator` **(** :ref:`String` label="", :ref:`int` id=-1 **)** | +---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_shortcut` **(** :ref:`ShortCut` shortcut, :ref:`int` id=-1, :ref:`bool` global=false **)** | +---------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -162,6 +162,8 @@ Theme Properties +---------------------------------+-------------------------+------------------------------+ | :ref:`Color` | font_color_hover | Color( 0.88, 0.88, 0.88, 1 ) | +---------------------------------+-------------------------+------------------------------+ +| :ref:`Color` | font_color_separator | Color( 0.88, 0.88, 0.88, 1 ) | ++---------------------------------+-------------------------+------------------------------+ | :ref:`StyleBox` | hover | | +---------------------------------+-------------------------+------------------------------+ | :ref:`int` | hseparation | 4 | @@ -227,7 +229,7 @@ Property Descriptions | *Getter* | get_allow_search() | +-----------+-------------------------+ -If ``true``, allows to navigate ``PopupMenu`` with letter keys. +If ``true``, allows navigating ``PopupMenu`` with letter keys. ---- @@ -428,9 +430,11 @@ An ``id`` can optionally be provided. If no ``id`` is provided, one will be crea .. _class_PopupMenu_method_add_separator: -- void **add_separator** **(** :ref:`String` label="" **)** +- void **add_separator** **(** :ref:`String` label="", :ref:`int` id=-1 **)** -Adds a separator between items. Separators also occupy an index. +Adds a separator between items. Separators also occupy an index, which you can set by using the ``id`` parameter. + +A ``label`` can optionally be provided, which will appear at the center of the separator. ---- @@ -706,7 +710,7 @@ Sets the metadata of an item, which may be of any type. You can later get it wit - void **set_item_multistate** **(** :ref:`int` idx, :ref:`int` state **)** -Sets the state of an multistate item. See :ref:`add_multistate_item` for details. +Sets the state of a multistate item. See :ref:`add_multistate_item` for details. ---- @@ -762,7 +766,7 @@ Toggles the check state of the item of the specified index ``idx``. - void **toggle_item_multistate** **(** :ref:`int` idx **)** -Cycle to the next state of an multistate item. See :ref:`add_multistate_item` for details. +Cycle to the next state of a multistate item. See :ref:`add_multistate_item` for details. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_primitivemesh.rst b/classes/class_primitivemesh.rst index 18c4b659c..2be954d8e 100644 --- a/classes/class_primitivemesh.rst +++ b/classes/class_primitivemesh.rst @@ -53,7 +53,7 @@ Property Descriptions | *Getter* | get_custom_aabb() | +-----------+------------------------------+ -Overrides the :ref:`AABB` with one defined by user for use with frustum culling. Especially useful to avoid unnexpected culling when using a shader to offset vertices. +Overrides the :ref:`AABB` with one defined by user for use with frustum culling. Especially useful to avoid unexpected culling when using a shader to offset vertices. ---- diff --git a/classes/class_projectsettings.rst b/classes/class_projectsettings.rst index ee6904225..c74a15fa0 100644 --- a/classes/class_projectsettings.rst +++ b/classes/class_projectsettings.rst @@ -22,6 +22,15 @@ When naming a Project Settings property, use the full path to the setting includ **Overriding:** Any project setting can be overridden by creating a file named ``override.cfg`` in the project's root directory. This can also be used in exported projects by placing this file in the same directory as the project binary. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/675 `_ + +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/677 `_ + Properties ---------- @@ -56,6 +65,10 @@ Properties +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`application/run/disable_stdout` | ``false`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`application/run/flush_stdout_on_print` | ``false`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`application/run/flush_stdout_on_print.debug` | ``true`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`application/run/frame_delay_msec` | ``0`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`application/run/low_processor_mode` | ``false`` | @@ -170,9 +183,11 @@ Properties +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`Color` | :ref:`debug/shapes/collision/contact_color` | ``Color( 1, 0.2, 0.1, 0.8 )`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`debug/shapes/collision/draw_2d_outlines` | ``true`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`debug/shapes/collision/max_contacts_displayed` | ``10000`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`debug/shapes/collision/shape_color` | ``Color( 0, 0.6, 0.7, 0.5 )`` | +| :ref:`Color` | :ref:`debug/shapes/collision/shape_color` | ``Color( 0, 0.6, 0.7, 0.42 )`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`Color` | :ref:`debug/shapes/navigation/disabled_geometry_color` | ``Color( 1, 0.7, 0.1, 0.4 )`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ @@ -270,6 +285,8 @@ Properties +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`input_devices/pointing/emulate_touch_from_mouse` | ``false`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`input_devices/pointing/ios/touch_delay` | ``0.15`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`layer_names/2d_physics/layer_1` | ``""`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`layer_names/2d_physics/layer_10` | ``""`` | @@ -442,7 +459,9 @@ Properties +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`logging/file_logging/max_log_files` | ``5`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`memory/limits/message_queue/max_size_kb` | ``1024`` | +| :ref:`int` | :ref:`memory/limits/command_queue/multithreading_queue_size_kb` | ``256`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`memory/limits/message_queue/max_size_kb` | ``4096`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`memory/limits/multithreaded_server/rid_pool_prealloc` | ``60`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ @@ -520,14 +539,26 @@ Properties +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`physics/3d/default_linear_damp` | ``0.1`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`physics/3d/godot_physics/use_bvh` | ``true`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`physics/3d/physics_engine` | ``"DEFAULT"`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`physics/common/enable_object_picking` | ``true`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`physics/common/enable_pause_aware_picking` | ``false`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`physics/common/physics_fps` | ``60`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`physics/common/physics_jitter_fix` | ``0.5`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`rendering/2d/options/ninepatch_mode` | ``1`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`rendering/2d/options/use_nvidia_rect_flicker_workaround` | ``false`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`rendering/2d/options/use_software_skinning` | ``true`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`rendering/2d/snapping/use_gpu_pixel_snap` | ``false`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`rendering/batching/debug/diagnose_frame` | ``false`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`rendering/batching/debug/flash_batching` | ``false`` | @@ -554,6 +585,14 @@ Properties +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/batching/precision/uv_contract_amount` | ``100`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`rendering/cpu_lightmapper/quality/high_quality_ray_count` | ``512`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`rendering/cpu_lightmapper/quality/low_quality_ray_count` | ``64`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`rendering/cpu_lightmapper/quality/medium_quality_ray_count` | ``256`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`rendering/cpu_lightmapper/quality/ultra_quality_ray_count` | ``1024`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`Color` | :ref:`rendering/environment/default_clear_color` | ``Color( 0.3, 0.3, 0.3, 1 )`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`rendering/environment/default_environment` | ``""`` | @@ -570,6 +609,8 @@ Properties +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/limits/buffers/immediate_buffer_size_kb` | ``2048`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`rendering/limits/rendering/max_lights_per_object` | ``32`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/limits/rendering/max_renderable_elements` | ``65536`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/limits/rendering/max_renderable_lights` | ``4096`` | @@ -578,10 +619,6 @@ Properties +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`rendering/limits/time/time_rollover_secs` | ``3600`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`rendering/quality/2d/use_nvidia_rect_flicker_workaround` | ``false`` | -+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`rendering/quality/2d/use_pixel_snap` | ``false`` | -+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`rendering/quality/depth/hdr` | ``true`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`rendering/quality/depth/hdr.mobile` | ``false`` | @@ -602,12 +639,20 @@ Properties +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/quality/filters/msaa` | ``0`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`rendering/quality/filters/use_debanding` | ``false`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`rendering/quality/filters/use_fxaa` | ``false`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`rendering/quality/filters/use_nearest_mipmap_filter` | ``false`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/quality/intended_usage/framebuffer_allocation` | ``2`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/quality/intended_usage/framebuffer_allocation.mobile` | ``3`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`rendering/quality/lightmapping/use_bicubic_sampling` | ``true`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`rendering/quality/lightmapping/use_bicubic_sampling.mobile` | ``false`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/quality/reflections/atlas_size` | ``2048`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/quality/reflections/atlas_subdiv` | ``8`` | @@ -650,6 +695,14 @@ Properties +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/quality/shadows/filter_mode.mobile` | ``0`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`rendering/quality/skinning/force_software_skinning` | ``false`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`rendering/quality/skinning/software_skinning_fallback` | ``true`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`rendering/quality/spatial_partitioning/render_tree_balance` | ``0.0`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`rendering/quality/spatial_partitioning/use_bvh` | ``true`` | ++-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`rendering/quality/subsurface_scattering/follow_surface` | ``false`` | +-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/quality/subsurface_scattering/quality` | ``1`` | @@ -678,37 +731,37 @@ Properties Methods ------- -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_property_info` **(** :ref:`Dictionary` hint **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear` **(** :ref:`String` name **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_order` **(** :ref:`String` name **)** |const| | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`get_setting` **(** :ref:`String` name **)** |const| | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`globalize_path` **(** :ref:`String` path **)** |const| | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_setting` **(** :ref:`String` name **)** |const| | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`load_resource_pack` **(** :ref:`String` pack, :ref:`bool` replace_files=true **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`localize_path` **(** :ref:`String` path **)** |const| | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`property_can_revert` **(** :ref:`String` name **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`property_get_revert` **(** :ref:`String` name **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`save` **(** **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`save_custom` **(** :ref:`String` file **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_initial_value` **(** :ref:`String` name, :ref:`Variant` value **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_order` **(** :ref:`String` name, :ref:`int` position **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_setting` **(** :ref:`String` name, :ref:`Variant` value **)** | -+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`add_property_info` **(** :ref:`Dictionary` hint **)** | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`clear` **(** :ref:`String` name **)** | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_order` **(** :ref:`String` name **)** |const| | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`get_setting` **(** :ref:`String` name **)** |const| | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`globalize_path` **(** :ref:`String` path **)** |const| | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`has_setting` **(** :ref:`String` name **)** |const| | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`load_resource_pack` **(** :ref:`String` pack, :ref:`bool` replace_files=true, :ref:`int` offset=0 **)** | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`localize_path` **(** :ref:`String` path **)** |const| | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`property_can_revert` **(** :ref:`String` name **)** | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`property_get_revert` **(** :ref:`String` name **)** | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`save` **(** **)** | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`save_custom` **(** :ref:`String` file **)** | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_initial_value` **(** :ref:`String` name, :ref:`Variant` value **)** | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_order` **(** :ref:`String` name, :ref:`int` position **)** | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_setting` **(** :ref:`String` name, :ref:`Variant` value **)** | ++---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Property Descriptions --------------------- @@ -835,7 +888,7 @@ Icon set in ``.icns`` format used on macOS to set the game's icon. This is done The project's name. It is used both by the Project Manager and by exporters. The project name can be translated by translating its value in localization files. The window title will be set to match the project name automatically on startup. -**Note:** Changing this value will also change the user data folder's path if :ref:`application/config/use_custom_user_dir` is ``false``. After renaming the project, you will no longer be able to access existing data in ``user://`` unless you rename the old folder to match the new project name. See `Data paths `_ in the documentation for more information. +**Note:** Changing this value will also change the user data folder's path if :ref:`application/config/use_custom_user_dir` is ``false``. After renaming the project, you will no longer be able to access existing data in ``user://`` unless you rename the old folder to match the new project name. See `Data paths `_ in the documentation for more information. ---- @@ -901,6 +954,38 @@ If ``true``, disables printing to standard output in an exported build. ---- +.. _class_ProjectSettings_property_application/run/flush_stdout_on_print: + +- :ref:`bool` **application/run/flush_stdout_on_print** + ++-----------+-----------+ +| *Default* | ``false`` | ++-----------+-----------+ + +If ``true``, flushes the standard output stream every time a line is printed. This affects both terminal logging and file logging. + +When running a project, this setting must be enabled if you want logs to be collected by service managers such as systemd/journalctl. This setting is disabled by default on release builds, since flushing on every printed line will negatively affect performance if lots of lines are printed in a rapid succession. Also, if this setting is enabled, logged files will still be written successfully if the application crashes or is otherwise killed by the user (without being closed "normally"). + +**Note:** Regardless of this setting, the standard error stream (``stderr``) is always flushed when a line is printed to it. + +Changes to this setting will only be applied upon restarting the application. + +---- + +.. _class_ProjectSettings_property_application/run/flush_stdout_on_print.debug: + +- :ref:`bool` **application/run/flush_stdout_on_print.debug** + ++-----------+----------+ +| *Default* | ``true`` | ++-----------+----------+ + +Debug build override for :ref:`application/run/flush_stdout_on_print`, as performance is less important during debugging. + +Changes to this setting will only be applied upon restarting the application. + +---- + .. _class_ProjectSettings_property_application/run/frame_delay_msec: - :ref:`int` **application/run/frame_delay_msec** @@ -1513,7 +1598,7 @@ Maximum number of frames per second allowed. The actual number of frames per sec If :ref:`display/window/vsync/use_vsync` is enabled, it takes precedence and the forced FPS number cannot exceed the monitor's refresh rate. -This setting is therefore mostly relevant for lowering the maximum FPS below VSync, e.g. to perform non real-time rendering of static frames, or test the project under lag conditions. +This setting is therefore mostly relevant for lowering the maximum FPS below VSync, e.g. to perform non-real-time rendering of static frames, or test the project under lag conditions. ---- @@ -1589,6 +1674,18 @@ Color of the contact points between collision shapes, visible when "Visible Coll ---- +.. _class_ProjectSettings_property_debug/shapes/collision/draw_2d_outlines: + +- :ref:`bool` **debug/shapes/collision/draw_2d_outlines** + ++-----------+----------+ +| *Default* | ``true`` | ++-----------+----------+ + +Sets whether 2D physics will display collision outlines in game when "Visible Collision Shapes" is enabled in the Debug menu. + +---- + .. _class_ProjectSettings_property_debug/shapes/collision/max_contacts_displayed: - :ref:`int` **debug/shapes/collision/max_contacts_displayed** @@ -1605,9 +1702,9 @@ Maximum number of contact points between collision shapes to display when "Visib - :ref:`Color` **debug/shapes/collision/shape_color** -+-----------+-------------------------------+ -| *Default* | ``Color( 0, 0.6, 0.7, 0.5 )`` | -+-----------+-------------------------------+ ++-----------+--------------------------------+ +| *Default* | ``Color( 0, 0.6, 0.7, 0.42 )`` | ++-----------+--------------------------------+ Color of the collision shapes, visible when "Visible Collision Shapes" is enabled in the Debug menu. @@ -1681,7 +1778,7 @@ Position offset for tooltips, relative to the mouse cursor's hotspot. | *Default* | ``false`` | +-----------+-----------+ -If ``true``, allows HiDPI display on Windows and macOS. This setting has no effect on desktop Linux, as DPI-awareness fallbacks are not supported there. +If ``true``, allows HiDPI display on Windows, macOS, and the HTML5 platform. This setting has no effect on desktop Linux, as DPI-awareness fallbacks are not supported there. ---- @@ -1753,7 +1850,9 @@ Sets the window background to transparent when it starts. | *Default* | ``false`` | +-----------+-----------+ -Force the window to be always on top. +Forces the main window to be always on top. + +**Note:** This setting is ignored on iOS, Android, and HTML5. ---- @@ -1765,7 +1864,9 @@ Force the window to be always on top. | *Default* | ``false`` | +-----------+-----------+ -Force the window to be borderless. +Forces the main window to be borderless. + +**Note:** This setting is ignored on iOS, Android, and HTML5. ---- @@ -1777,7 +1878,11 @@ Force the window to be borderless. | *Default* | ``false`` | +-----------+-----------+ -Sets the window to full screen when it starts. +Sets the main window to full screen when the project starts. Note that this is not *exclusive* fullscreen. On Windows and Linux, a borderless window is used to emulate fullscreen. On macOS, a new desktop is used to display the running project. + +Regardless of the platform, enabling fullscreen will change the window size to match the monitor's size. Therefore, make sure your project supports `multiple resolutions `_ when enabling fullscreen mode. + +**Note:** This setting is ignored on iOS, Android, and HTML5. ---- @@ -1803,6 +1908,8 @@ Sets the game's main viewport height. On desktop platforms, this is the default Allows the window to be resizable by default. +**Note:** This setting is ignored on iOS and Android. + ---- .. _class_ProjectSettings_property_display/window/size/test_height: @@ -1887,7 +1994,7 @@ If ``Use Vsync`` is enabled and this setting is ``true``, enables vertical synch | *Default* | ``"res://script_templates"`` | +-----------+------------------------------+ -Search path for project-specific script templates. Script templates will be search both in the editor-specific path and in this project-specific path. +Search path for project-specific script templates. Godot will search for script templates both in the editor-specific path and in this project-specific path. ---- @@ -2163,6 +2270,18 @@ If ``true``, sends touch input events when clicking or dragging the mouse. ---- +.. _class_ProjectSettings_property_input_devices/pointing/ios/touch_delay: + +- :ref:`float` **input_devices/pointing/ios/touch_delay** + ++-----------+----------+ +| *Default* | ``0.15`` | ++-----------+----------+ + +Default delay for touch events. This only affects iOS devices. + +---- + .. _class_ProjectSettings_property_layer_names/2d_physics/layer_1: - :ref:`String` **layer_names/2d_physics/layer_1** @@ -3167,6 +3286,8 @@ If ``true``, logs all output to files. | *Default* | ``true`` | +-----------+----------+ +Desktop override for :ref:`logging/file_logging/enable_file_logging`, as log files are not readily accessible on mobile/Web platforms. + ---- .. _class_ProjectSettings_property_logging/file_logging/log_path: @@ -3193,12 +3314,22 @@ Specifies the maximum amount of log files allowed (used for rotation). ---- +.. _class_ProjectSettings_property_memory/limits/command_queue/multithreading_queue_size_kb: + +- :ref:`int` **memory/limits/command_queue/multithreading_queue_size_kb** + ++-----------+---------+ +| *Default* | ``256`` | ++-----------+---------+ + +---- + .. _class_ProjectSettings_property_memory/limits/message_queue/max_size_kb: - :ref:`int` **memory/limits/message_queue/max_size_kb** +-----------+----------+ -| *Default* | ``1024`` | +| *Default* | ``4096`` | +-----------+----------+ Godot uses a message queue to defer some function calls. If you run out of space on it (you will see an error), you can increase the size here. @@ -3273,7 +3404,7 @@ Maximum number of warnings allowed to be sent as output from the debugger. Over | *Default* | ``16`` | +-----------+--------+ -Default size of packet peer stream for deserializing Godot data. Over this size, data is dropped. +Default size of packet peer stream for deserializing Godot data (in bytes, specified as a power of two). The default value ``16`` is equal to 65,536 bytes. Over this size, data is dropped. ---- @@ -3493,6 +3624,8 @@ Cell size used for the broad-phase 2D hash grid algorithm (in pixels). The default angular damp in 2D. +**Note:** Good values are in the range ``0`` to ``1``. At value ``0`` objects will keep moving with the same velocity. Values greater than ``1`` will aim to reduce the velocity to ``0`` in less than a second e.g. a value of ``2`` will aim to reduce the velocity to ``0`` in half a second. A value equal to or greater than the physics frame rate (:ref:`physics/common/physics_fps`, ``60`` by default) will bring the object to a stop in one iteration. + ---- .. _class_ProjectSettings_property_physics/2d/default_gravity: @@ -3543,6 +3676,8 @@ The default gravity direction in 2D. The default linear damp in 2D. +**Note:** Good values are in the range ``0`` to ``1``. At value ``0`` objects will keep moving with the same velocity. Values greater than ``1`` will aim to reduce the velocity to ``0`` in less than a second e.g. a value of ``2`` will aim to reduce the velocity to ``0`` in half a second. A value equal to or greater than the physics frame rate (:ref:`physics/common/physics_fps`, ``60`` by default) will bring the object to a stop in one iteration. + ---- .. _class_ProjectSettings_property_physics/2d/large_object_surface_threshold_in_cells: @@ -3643,6 +3778,8 @@ Sets whether the 3D physics world will be created with support for :ref:`SoftBod The default angular damp in 3D. +**Note:** Good values are in the range ``0`` to ``1``. At value ``0`` objects will keep moving with the same velocity. Values greater than ``1`` will aim to reduce the velocity to ``0`` in less than a second e.g. a value of ``2`` will aim to reduce the velocity to ``0`` in half a second. A value equal to or greater than the physics frame rate (:ref:`physics/common/physics_fps`, ``60`` by default) will bring the object to a stop in one iteration. + ---- .. _class_ProjectSettings_property_physics/3d/default_gravity: @@ -3693,6 +3830,20 @@ The default gravity direction in 3D. The default linear damp in 3D. +**Note:** Good values are in the range ``0`` to ``1``. At value ``0`` objects will keep moving with the same velocity. Values greater than ``1`` will aim to reduce the velocity to ``0`` in less than a second e.g. a value of ``2`` will aim to reduce the velocity to ``0`` in half a second. A value equal to or greater than the physics frame rate (:ref:`physics/common/physics_fps`, ``60`` by default) will bring the object to a stop in one iteration. + +---- + +.. _class_ProjectSettings_property_physics/3d/godot_physics/use_bvh: + +- :ref:`bool` **physics/3d/godot_physics/use_bvh** + ++-----------+----------+ +| *Default* | ``true`` | ++-----------+----------+ + +Enables the use of bounding volume hierarchy instead of octree for physics spatial partitioning. This may give better performance. + ---- .. _class_ProjectSettings_property_physics/3d/physics_engine: @@ -3721,6 +3872,24 @@ Enables :ref:`Viewport.physics_object_picking` **physics/common/enable_pause_aware_picking** + ++-----------+-----------+ +| *Default* | ``false`` | ++-----------+-----------+ + +If enabled, 2D and 3D physics picking behaves this way in relation to pause: + +- When pause is started, every collision object that is hovered or captured (3D only) is released from that condition, getting the relevant mouse-exit callback, unless its pause mode makes it immune to pause. + +- During pause, picking only considers collision objects immune to pause, sending input events and enter/exit callbacks to them as expected. + +If disabled, the legacy behavior is used, which consists in queuing the picking input events during pause (so nodes won't get them) and flushing that queue on resume, against the state of the 2D/3D world at that point. + +---- + .. _class_ProjectSettings_property_physics/common/physics_fps: - :ref:`int` **physics/common/physics_fps** @@ -3749,6 +3918,68 @@ Fix to improve physics jitter, specially on monitors where refresh rate is diffe ---- +.. _class_ProjectSettings_property_rendering/2d/options/ninepatch_mode: + +- :ref:`int` **rendering/2d/options/ninepatch_mode** + ++-----------+-------+ +| *Default* | ``1`` | ++-----------+-------+ + +Choose between fixed mode where corner scalings are preserved matching the artwork, and scaling mode. + +Not available in GLES3 when :ref:`rendering/batching/options/use_batching` is off. + +---- + +.. _class_ProjectSettings_property_rendering/2d/options/use_nvidia_rect_flicker_workaround: + +- :ref:`bool` **rendering/2d/options/use_nvidia_rect_flicker_workaround** + ++-----------+-----------+ +| *Default* | ``false`` | ++-----------+-----------+ + +Some NVIDIA GPU drivers have a bug which produces flickering issues for the ``draw_rect`` method, especially as used in :ref:`TileMap`. Refer to `GitHub issue 9913 `_ for details. + +If ``true``, this option enables a "safe" code path for such NVIDIA GPUs at the cost of performance. This option affects GLES2 and GLES3 rendering, but only on desktop platforms. + +---- + +.. _class_ProjectSettings_property_rendering/2d/options/use_software_skinning: + +- :ref:`bool` **rendering/2d/options/use_software_skinning** + ++-----------+----------+ +| *Default* | ``true`` | ++-----------+----------+ + +If ``true``, performs 2D skinning on the CPU rather than the GPU. This provides greater compatibility with a wide range of hardware, and also may be faster in some circumstances. + +Currently only available when :ref:`rendering/batching/options/use_batching` is active. + +**Note:** Antialiased software skinned polys are not supported, and will be rendered without antialiasing. + +**Note:** Custom shaders that use the ``VERTEX`` built-in operate with ``VERTEX`` position *after* skinning, whereas with hardware skinning, ``VERTEX`` is the position *before* skinning. + +---- + +.. _class_ProjectSettings_property_rendering/2d/snapping/use_gpu_pixel_snap: + +- :ref:`bool` **rendering/2d/snapping/use_gpu_pixel_snap** + ++-----------+-----------+ +| *Default* | ``false`` | ++-----------+-----------+ + +If ``true``, forces snapping of vertices to pixels in 2D rendering. May help in some pixel art styles. + +This snapping is performed on the GPU in the vertex shader. + +Consider using the project setting :ref:`rendering/batching/precision/uv_contract` to prevent artifacts. + +---- + .. _class_ProjectSettings_property_rendering/batching/debug/diagnose_frame: - :ref:`bool` **rendering/batching/debug/diagnose_frame** @@ -3817,9 +4048,7 @@ Enabling this setting uses the legacy method to draw batches containing only one | *Default* | ``true`` | +-----------+----------+ -Turns batching on and off. Batching increases performance by reducing the amount of graphics API drawcalls. - -**Note:** Currently only effective when using the GLES2 renderer. +Turns 2D batching on and off. Batching increases performance by reducing the amount of graphics API drawcalls. ---- @@ -3831,9 +4060,7 @@ Turns batching on and off. Batching increases performance by reducing the amount | *Default* | ``true`` | +-----------+----------+ -Switches on batching within the editor. - -**Note:** Currently only effective when using the GLES2 renderer. +Switches on 2D batching within the editor. ---- @@ -3913,6 +4140,54 @@ Use the default unless correcting for a problem on particular hardware. ---- +.. _class_ProjectSettings_property_rendering/cpu_lightmapper/quality/high_quality_ray_count: + +- :ref:`int` **rendering/cpu_lightmapper/quality/high_quality_ray_count** + ++-----------+---------+ +| *Default* | ``512`` | ++-----------+---------+ + +Amount of light samples taken when using :ref:`BakedLightmap.BAKE_QUALITY_HIGH`. + +---- + +.. _class_ProjectSettings_property_rendering/cpu_lightmapper/quality/low_quality_ray_count: + +- :ref:`int` **rendering/cpu_lightmapper/quality/low_quality_ray_count** + ++-----------+--------+ +| *Default* | ``64`` | ++-----------+--------+ + +Amount of light samples taken when using :ref:`BakedLightmap.BAKE_QUALITY_LOW`. + +---- + +.. _class_ProjectSettings_property_rendering/cpu_lightmapper/quality/medium_quality_ray_count: + +- :ref:`int` **rendering/cpu_lightmapper/quality/medium_quality_ray_count** + ++-----------+---------+ +| *Default* | ``256`` | ++-----------+---------+ + +Amount of light samples taken when using :ref:`BakedLightmap.BAKE_QUALITY_MEDIUM`. + +---- + +.. _class_ProjectSettings_property_rendering/cpu_lightmapper/quality/ultra_quality_ray_count: + +- :ref:`int` **rendering/cpu_lightmapper/quality/ultra_quality_ray_count** + ++-----------+----------+ +| *Default* | ``1024`` | ++-----------+----------+ + +Amount of light samples taken when using :ref:`BakedLightmap.BAKE_QUALITY_ULTRA`. + +---- + .. _class_ProjectSettings_property_rendering/environment/default_clear_color: - :ref:`Color` **rendering/environment/default_clear_color** @@ -4011,6 +4286,18 @@ Max buffer size for drawing immediate objects (ImmediateGeometry nodes). Nodes u ---- +.. _class_ProjectSettings_property_rendering/limits/rendering/max_lights_per_object: + +- :ref:`int` **rendering/limits/rendering/max_lights_per_object** + ++-----------+--------+ +| *Default* | ``32`` | ++-----------+--------+ + +Max number of lights renderable per object. This is further limited by hardware support. Most devices only support 409 lights, while many devices (especially mobile) only support 102. Setting this low will slightly reduce memory usage and may decrease shader compile times. + +---- + .. _class_ProjectSettings_property_rendering/limits/rendering/max_renderable_elements: - :ref:`int` **rendering/limits/rendering/max_renderable_elements** @@ -4019,7 +4306,7 @@ Max buffer size for drawing immediate objects (ImmediateGeometry nodes). Nodes u | *Default* | ``65536`` | +-----------+-----------+ -Max amount of elements renderable in a frame. If more than this are visible per frame, they will be dropped. Keep in mind elements refer to mesh surfaces and not meshes themselves. +Max amount of elements renderable in a frame. If more elements than this are visible per frame, they will not be drawn. Keep in mind elements refer to mesh surfaces and not meshes themselves. Setting this low will slightly reduce memory usage and may decrease shader compile times, particularly on web. For most uses, the default value is suitable, but consider lowering as much as possible on web export. ---- @@ -4031,7 +4318,7 @@ Max amount of elements renderable in a frame. If more than this are visible per | *Default* | ``4096`` | +-----------+----------+ -Max number of lights renderable in a frame. If more than this number are used, they will be ignored. On some systems (particularly web) setting this number as low as possible can increase the speed of shader compilation. +Max number of lights renderable in a frame. If more lights than this number are used, they will be ignored. Setting this low will slightly reduce memory usage and may decrease shader compile times, particularly on web. For most uses, the default value is suitable, but consider lowering as much as possible on web export. ---- @@ -4043,7 +4330,7 @@ Max number of lights renderable in a frame. If more than this number are used, t | *Default* | ``1024`` | +-----------+----------+ -Max number of reflection probes renderable in a frame. If more than this number are used, they will be ignored. On some systems (particularly web) setting this number as low as possible can increase the speed of shader compilation. +Max number of reflection probes renderable in a frame. If more reflection probes than this number are used, they will be ignored. Setting this low will slightly reduce memory usage and may decrease shader compile times, particularly on web. For most uses, the default value is suitable, but consider lowering as much as possible on web export. ---- @@ -4059,34 +4346,6 @@ Shaders have a time variable that constantly increases. At some point, it needs ---- -.. _class_ProjectSettings_property_rendering/quality/2d/use_nvidia_rect_flicker_workaround: - -- :ref:`bool` **rendering/quality/2d/use_nvidia_rect_flicker_workaround** - -+-----------+-----------+ -| *Default* | ``false`` | -+-----------+-----------+ - -Some NVIDIA GPU drivers have a bug which produces flickering issues for the ``draw_rect`` method, especially as used in :ref:`TileMap`. Refer to `GitHub issue 9913 `_ for details. - -If ``true``, this option enables a "safe" code path for such NVIDIA GPUs at the cost of performance. This option affects GLES2 and GLES3 rendering, but only on desktop platforms. - ----- - -.. _class_ProjectSettings_property_rendering/quality/2d/use_pixel_snap: - -- :ref:`bool` **rendering/quality/2d/use_pixel_snap** - -+-----------+-----------+ -| *Default* | ``false`` | -+-----------+-----------+ - -If ``true``, forces snapping of polygons to pixels in 2D rendering. May help in some pixel art styles. - -Consider using the project setting :ref:`rendering/batching/precision/uv_contract` to prevent artifacts. - ----- - .. _class_ProjectSettings_property_rendering/quality/depth/hdr: - :ref:`bool` **rendering/quality/depth/hdr** @@ -4215,6 +4474,32 @@ Sets the number of MSAA samples to use. MSAA is used to reduce aliasing around t ---- +.. _class_ProjectSettings_property_rendering/quality/filters/use_debanding: + +- :ref:`bool` **rendering/quality/filters/use_debanding** + ++-----------+-----------+ +| *Default* | ``false`` | ++-----------+-----------+ + +If ``true``, uses a fast post-processing filter to make banding significantly less visible. In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger. + +**Note:** Only available on the GLES3 backend. :ref:`rendering/quality/depth/hdr` must also be ``true`` for debanding to be effective. + +---- + +.. _class_ProjectSettings_property_rendering/quality/filters/use_fxaa: + +- :ref:`bool` **rendering/quality/filters/use_fxaa** + ++-----------+-----------+ +| *Default* | ``false`` | ++-----------+-----------+ + +Enables FXAA in the root Viewport. FXAA is a popular screen-space antialiasing method, which is fast but will make the image look blurry, especially at lower resolutions. It can still work relatively well at large resolutions such as 1440p and 4K. + +---- + .. _class_ProjectSettings_property_rendering/quality/filters/use_nearest_mipmap_filter: - :ref:`bool` **rendering/quality/filters/use_nearest_mipmap_filter** @@ -4251,6 +4536,30 @@ Lower-end override for :ref:`rendering/quality/intended_usage/framebuffer_alloca ---- +.. _class_ProjectSettings_property_rendering/quality/lightmapping/use_bicubic_sampling: + +- :ref:`bool` **rendering/quality/lightmapping/use_bicubic_sampling** + ++-----------+----------+ +| *Default* | ``true`` | ++-----------+----------+ + +Enable usage of bicubic sampling in baked lightmaps. This results in smoother looking lighting at the expense of more bandwidth usage. On GLES2, changes to this setting will only be applied upon restarting the application. + +---- + +.. _class_ProjectSettings_property_rendering/quality/lightmapping/use_bicubic_sampling.mobile: + +- :ref:`bool` **rendering/quality/lightmapping/use_bicubic_sampling.mobile** + ++-----------+-----------+ +| *Default* | ``false`` | ++-----------+-----------+ + +Lower-end override for :ref:`rendering/quality/lightmapping/use_bicubic_sampling` on mobile devices, in order to reduce bandwidth usage. + +---- + .. _class_ProjectSettings_property_rendering/quality/reflections/atlas_size: - :ref:`int` **rendering/quality/reflections/atlas_size** @@ -4491,6 +4800,8 @@ Lower-end override for :ref:`rendering/quality/shadow_atlas/size` **rendering/quality/skinning/force_software_skinning** + ++-----------+-----------+ +| *Default* | ``false`` | ++-----------+-----------+ + +Forces :ref:`MeshInstance` to always perform skinning on the CPU (applies to both GLES2 and GLES3). + +See also :ref:`rendering/quality/skinning/software_skinning_fallback`. + +---- + +.. _class_ProjectSettings_property_rendering/quality/skinning/software_skinning_fallback: + +- :ref:`bool` **rendering/quality/skinning/software_skinning_fallback** + ++-----------+----------+ +| *Default* | ``true`` | ++-----------+----------+ + +Allows :ref:`MeshInstance` to perform skinning on the CPU when the hardware doesn't support the default GPU skinning process with GLES2. + +If ``false``, an alternative skinning process on the GPU is used in this case (slower in most cases). + +See also :ref:`rendering/quality/skinning/force_software_skinning`. + +**Note:** When the software skinning fallback is triggered, custom vertex shaders will behave in a different way, because the bone transform will be already applied to the modelview matrix. + +---- + +.. _class_ProjectSettings_property_rendering/quality/spatial_partitioning/render_tree_balance: + +- :ref:`float` **rendering/quality/spatial_partitioning/render_tree_balance** + ++-----------+---------+ +| *Default* | ``0.0`` | ++-----------+---------+ + +The rendering octree balance can be changed to favor smaller (``0``), or larger (``1``) branches. + +Larger branches can increase performance significantly in some projects. + +---- + +.. _class_ProjectSettings_property_rendering/quality/spatial_partitioning/use_bvh: + +- :ref:`bool` **rendering/quality/spatial_partitioning/use_bvh** + ++-----------+----------+ +| *Default* | ``true`` | ++-----------+----------+ + +Enables the use of bounding volume hierarchy instead of octree for rendering spatial partitioning. This may give better performance. + +---- + .. _class_ProjectSettings_property_rendering/quality/subsurface_scattering/follow_surface: - :ref:`bool` **rendering/quality/subsurface_scattering/follow_surface** @@ -4713,7 +5082,23 @@ Returns the value of a setting. - :ref:`String` **globalize_path** **(** :ref:`String` path **)** |const| -Converts a localized path (``res://``) to a full native OS path. +Returns the absolute, native OS path corresponding to the localized ``path`` (starting with ``res://`` or ``user://``). The returned path will vary depending on the operating system and user preferences. See `File paths in Godot projects `_ to see what those paths convert to. See also :ref:`localize_path`. + +**Note:** :ref:`globalize_path` with ``res://`` will not work in an exported project. Instead, prepend the executable's base directory to the path when running from an exported project: + +:: + + var path = "" + if OS.has_feature("editor"): + # Running from an editor binary. + # `path` will contain the absolute path to `hello.txt` located in the project root. + path = ProjectSettings.globalize_path("res://hello.txt") + else: + # Running from an exported project. + # `path` will contain the absolute path to `hello.txt` next to the executable. + # This is *not* identical to using `ProjectSettings.globalize_path()` with a `res://` path, + # but is close enough in spirit. + path = OS.get_executable_path().get_base_dir().plus_file("hello.txt") ---- @@ -4727,19 +5112,21 @@ Returns ``true`` if a configuration value is present. .. _class_ProjectSettings_method_load_resource_pack: -- :ref:`bool` **load_resource_pack** **(** :ref:`String` pack, :ref:`bool` replace_files=true **)** +- :ref:`bool` **load_resource_pack** **(** :ref:`String` pack, :ref:`bool` replace_files=true, :ref:`int` offset=0 **)** Loads the contents of the .pck or .zip file specified by ``pack`` into the resource filesystem (``res://``). Returns ``true`` on success. **Note:** If a file from ``pack`` shares the same path as a file already in the resource filesystem, any attempts to load that file will use the file from ``pack`` unless ``replace_files`` is set to ``false``. +**Note:** The optional ``offset`` parameter can be used to specify the offset in bytes to the start of the resource pack. This is only supported for .pck files. + ---- .. _class_ProjectSettings_method_localize_path: - :ref:`String` **localize_path** **(** :ref:`String` path **)** |const| -Convert a path to a localized path (``res://`` path). +Returns the localized path (starting with ``res://``) corresponding to the absolute, native OS ``path``. See also :ref:`globalize_path`. ---- @@ -4765,13 +5152,15 @@ Returns the specified property's initial value. Returns ``null`` if the property Saves the configuration to the ``project.godot`` file. +**Note:** This method is intended to be used by editor plugins, as modified ``ProjectSettings`` can't be loaded back in the running app. If you want to change project settings in exported projects, use :ref:`save_custom` to save ``override.cfg`` file. + ---- .. _class_ProjectSettings_method_save_custom: - :ref:`Error` **save_custom** **(** :ref:`String` file **)** -Saves the configuration to a custom file. The file extension must be ``.godot`` (to save in text-based :ref:`ConfigFile` format) or ``.binary`` (to save in binary format). +Saves the configuration to a custom file. The file extension must be ``.godot`` (to save in text-based :ref:`ConfigFile` format) or ``.binary`` (to save in binary format). You can also save ``override.cfg`` file, which is also text, but can be used in exported projects unlike other formats. ---- diff --git a/classes/class_proximitygroup.rst b/classes/class_proximitygroup.rst index c47003898..c81ceadab 100644 --- a/classes/class_proximitygroup.rst +++ b/classes/class_proximitygroup.rst @@ -32,16 +32,16 @@ Properties Methods ------- -+------+------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`broadcast` **(** :ref:`String` name, :ref:`Variant` parameters **)** | -+------+------------------------------------------------------------------------------------------------------------------------------------------------+ ++------+--------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`broadcast` **(** :ref:`String` method, :ref:`Variant` parameters **)** | ++------+--------------------------------------------------------------------------------------------------------------------------------------------------+ Signals ------- .. _class_ProximityGroup_signal_broadcast: -- **broadcast** **(** :ref:`String` group_name, :ref:`Array` parameters **)** +- **broadcast** **(** :ref:`String` method, :ref:`Array` parameters **)** Enumerations ------------ @@ -106,7 +106,7 @@ Method Descriptions .. _class_ProximityGroup_method_broadcast: -- void **broadcast** **(** :ref:`String` name, :ref:`Variant` parameters **)** +- void **broadcast** **(** :ref:`String` method, :ref:`Variant` parameters **)** .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_quadmesh.rst b/classes/class_quadmesh.rst index fdf992697..8484a3dbf 100644 --- a/classes/class_quadmesh.rst +++ b/classes/class_quadmesh.rst @@ -18,6 +18,13 @@ Description Class representing a square :ref:`PrimitiveMesh`. This flat mesh does not have a thickness. By default, this mesh is aligned on the X and Y axes; this default rotation is more suited for use with billboarded materials. Unlike :ref:`PlaneMesh`, this mesh doesn't provide subdivision options. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/127 `_ + +- `https://godotengine.org/asset-library/asset/129 `_ + Properties ---------- diff --git a/classes/class_quat.rst b/classes/class_quat.rst index d98140327..3f1b4585d 100644 --- a/classes/class_quat.rst +++ b/classes/class_quat.rst @@ -25,6 +25,8 @@ Tutorials - `#interpolating-with-quaternions <../tutorials/3d/using_transforms.html#interpolating-with-quaternions>`_ in :doc:`../tutorials/3d/using_transforms` +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- @@ -208,7 +210,7 @@ Returns the inverse of the quaternion. - :ref:`bool` **is_equal_approx** **(** :ref:`Quat` quat **)** -Returns ``true`` if this quaterion and ``quat`` are approximately equal, by running :ref:`@GDScript.is_equal_approx` on each component. +Returns ``true`` if this quaternion and ``quat`` are approximately equal, by running :ref:`@GDScript.is_equal_approx` on each component. ---- diff --git a/classes/class_randomnumbergenerator.rst b/classes/class_randomnumbergenerator.rst index e1ee81a59..d3a88b7c0 100644 --- a/classes/class_randomnumbergenerator.rst +++ b/classes/class_randomnumbergenerator.rst @@ -29,12 +29,16 @@ To generate a random float number (within a given range) based on a time-dependa rng.randomize() var my_random_number = rng.randf_range(-10.0, 10.0) +**Note:** The default values of :ref:`seed` and :ref:`state` properties are pseudo-random, and changes when calling :ref:`randomize`. The ``0`` value documented here is a placeholder, and not the actual default seed. + Properties ---------- -+-----------------------+--------------------------------------------------------+--------------------------+ -| :ref:`int` | :ref:`seed` | ``-6398989897141750821`` | -+-----------------------+--------------------------------------------------------+--------------------------+ ++-----------------------+----------------------------------------------------------+-------+ +| :ref:`int` | :ref:`seed` | ``0`` | ++-----------------------+----------------------------------------------------------+-------+ +| :ref:`int` | :ref:`state` | ``0`` | ++-----------------------+----------------------------------------------------------+-------+ Methods ------- @@ -60,18 +64,55 @@ Property Descriptions - :ref:`int` **seed** -+-----------+--------------------------+ -| *Default* | ``-6398989897141750821`` | -+-----------+--------------------------+ -| *Setter* | set_seed(value) | -+-----------+--------------------------+ -| *Getter* | get_seed() | -+-----------+--------------------------+ ++-----------+-----------------+ +| *Default* | ``0`` | ++-----------+-----------------+ +| *Setter* | set_seed(value) | ++-----------+-----------------+ +| *Getter* | get_seed() | ++-----------+-----------------+ -The seed used by the random number generator. A given seed will give a reproducible sequence of pseudo-random numbers. +Initializes the random number generator state based on the given seed value. A given seed will give a reproducible sequence of pseudo-random numbers. **Note:** The RNG does not have an avalanche effect, and can output similar random streams given similar seeds. Consider using a hash function to improve your seed quality if they're sourced externally. +**Note:** Setting this property produces a side effect of changing the internal :ref:`state`, so make sure to initialize the seed *before* modifying the :ref:`state`: + +:: + + var rng = RandomNumberGenerator.new() + rng.seed = hash("Godot") + rng.state = 100 # Restore to some previously saved state. + +**Warning:** the getter of this property returns the previous :ref:`state`, and not the initial seed value, which is going to be fixed in Godot 4.0. + +---- + +.. _class_RandomNumberGenerator_property_state: + +- :ref:`int` **state** + ++-----------+------------------+ +| *Default* | ``0`` | ++-----------+------------------+ +| *Setter* | set_state(value) | ++-----------+------------------+ +| *Getter* | get_state() | ++-----------+------------------+ + +The current state of the random number generator. Save and restore this property to restore the generator to a previous state: + +:: + + var rng = RandomNumberGenerator.new() + print(rng.randf()) + var saved_state = rng.state # Store current state. + print(rng.randf()) # Advance internal state. + rng.state = saved_state # Restore the state. + print(rng.randf()) # Prints the same value as in previous. + +**Note:** Do not set state to arbitrary values, since the random number generator requires the state to have certain qualities to behave properly. It should only be set to values that came from the state property itself. To initialize the random number generator with arbitrary input, use :ref:`seed` instead. + Method Descriptions ------------------- diff --git a/classes/class_raycast.rst b/classes/class_raycast.rst index d38affc47..b9cbde177 100644 --- a/classes/class_raycast.rst +++ b/classes/class_raycast.rst @@ -31,6 +31,8 @@ Tutorials - :doc:`../tutorials/physics/ray-casting` +- `https://godotengine.org/asset-library/asset/676 `_ + Properties ---------- @@ -142,7 +144,7 @@ If ``true``, collision with :ref:`PhysicsBody`\ s will be rep | *Getter* | get_collision_mask() | +-----------+---------------------------+ -The ray's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. See `Collision layers and masks `_ in the documentation for more information. +The ray's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. See `Collision layers and masks `_ in the documentation for more information. ---- diff --git a/classes/class_raycast2d.rst b/classes/class_raycast2d.rst index c8a4e3a6b..5d91ce355 100644 --- a/classes/class_raycast2d.rst +++ b/classes/class_raycast2d.rst @@ -142,7 +142,7 @@ If ``true``, collision with :ref:`PhysicsBody2D`\ s will be | *Getter* | get_collision_mask() | +-----------+---------------------------+ -The ray's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. See `Collision layers and masks `_ in the documentation for more information. +The ray's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. See `Collision layers and masks `_ in the documentation for more information. ---- diff --git a/classes/class_rect2.rst b/classes/class_rect2.rst index 896ceca20..7659c1ae9 100644 --- a/classes/class_rect2.rst +++ b/classes/class_rect2.rst @@ -14,13 +14,21 @@ Rect2 Description ----------- -Rect2 consists of a position, a size, and several utility functions. It is typically used for fast overlap tests. +``Rect2`` consists of a position, a size, and several utility functions. It is typically used for fast overlap tests. + +It uses floating-point coordinates. + +The 3D counterpart to ``Rect2`` is :ref:`AABB`. Tutorials --------- - :doc:`../tutorials/math/index` +- :doc:`../tutorials/math/vector_math` + +- :doc:`../tutorials/math/vectors_advanced` + Properties ---------- @@ -102,7 +110,7 @@ Beginning corner. Typically has values lower than :ref:`end` to :ref:`end`. Typically all components are positive. +Size from :ref:`position` to :ref:`end`. Typically, all components are positive. If the size is negative, you can use :ref:`abs` to fix it. diff --git a/classes/class_rectangleshape2d.rst b/classes/class_rectangleshape2d.rst index 0f8a8fa9d..6e52f0752 100644 --- a/classes/class_rectangleshape2d.rst +++ b/classes/class_rectangleshape2d.rst @@ -18,6 +18,13 @@ Description Rectangle shape for 2D collisions. This shape is useful for modeling box-like 2D objects. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/121 `_ + +- `https://godotengine.org/asset-library/asset/113 `_ + Properties ---------- diff --git a/classes/class_reference.rst b/classes/class_reference.rst index 8fab16c98..959c904ae 100644 --- a/classes/class_reference.rst +++ b/classes/class_reference.rst @@ -20,10 +20,12 @@ Description Base class for any object that keeps a reference count. :ref:`Resource` and many other helper objects inherit this class. -Unlike :ref:`Object`\ s, References keep an internal reference counter so that they are automatically released when no longer in use, and only then. References therefore do not need to be freed manually with :ref:`Object.free`. +Unlike other :ref:`Object` types, References keep an internal reference counter so that they are automatically released when no longer in use, and only then. References therefore do not need to be freed manually with :ref:`Object.free`. In the vast majority of use cases, instantiating and using ``Reference``-derived types is all you need to do. The methods provided in this class are only for advanced users, and can cause issues if misused. +**Note:** In C#, references will not be freed instantly after they are no longer in use. Instead, garbage collection will run periodically and will free references that are no longer in use. This means that unused references will linger on for a while before being removed. + Tutorials --------- diff --git a/classes/class_referencerect.rst b/classes/class_referencerect.rst index f99f22b52..3e2604466 100644 --- a/classes/class_referencerect.rst +++ b/classes/class_referencerect.rst @@ -16,7 +16,7 @@ Reference frame for GUI. Description ----------- -A rectangle box that displays only a :ref:`border_color` border color around its rectangle. ``ReferenceRect`` has no fill :ref:`Color`. +A rectangle box that displays only a :ref:`border_color` border color around its rectangle. ``ReferenceRect`` has no fill :ref:`Color`. If you need to display a rectangle filled with a solid color, consider using :ref:`ColorRect` instead. Properties ---------- @@ -24,6 +24,8 @@ Properties +---------------------------+----------------------------------------------------------------+-------------------------+ | :ref:`Color` | :ref:`border_color` | ``Color( 1, 0, 0, 1 )`` | +---------------------------+----------------------------------------------------------------+-------------------------+ +| :ref:`float` | :ref:`border_width` | ``1.0`` | ++---------------------------+----------------------------------------------------------------+-------------------------+ | :ref:`bool` | :ref:`editor_only` | ``true`` | +---------------------------+----------------------------------------------------------------+-------------------------+ @@ -46,6 +48,22 @@ Sets the border :ref:`Color` of the ``ReferenceRect``. ---- +.. _class_ReferenceRect_property_border_width: + +- :ref:`float` **border_width** + ++-----------+-------------------------+ +| *Default* | ``1.0`` | ++-----------+-------------------------+ +| *Setter* | set_border_width(value) | ++-----------+-------------------------+ +| *Getter* | get_border_width() | ++-----------+-------------------------+ + +Sets the border width of the ``ReferenceRect``. The border grows both inwards and outwards with respect to the rectangle box. + +---- + .. _class_ReferenceRect_property_editor_only: - :ref:`bool` **editor_only** diff --git a/classes/class_regex.rst b/classes/class_regex.rst index 6095f6a46..2a17f91f2 100644 --- a/classes/class_regex.rst +++ b/classes/class_regex.rst @@ -64,8 +64,8 @@ If you need to process multiple results, :ref:`search_all`_ library. You can view the full pattern reference `here `_. diff --git a/classes/class_resource.rst b/classes/class_resource.rst index ba27bc6c2..998e5b1f8 100644 --- a/classes/class_resource.rst +++ b/classes/class_resource.rst @@ -18,7 +18,9 @@ Base class for all resources. Description ----------- -Resource is the base class for all Godot-specific resource types, serving primarily as data containers. Unlike :ref:`Object`\ s, they are reference-counted and freed when no longer in use. They are also cached once loaded from disk, so that any further attempts to load a resource from a given path will return the same reference (all this in contrast to a :ref:`Node`, which is not reference-counted and can be instanced from disk as many times as desired). Resources can be saved externally on disk or bundled into another object, such as a :ref:`Node` or another resource. +Resource is the base class for all Godot-specific resource types, serving primarily as data containers. Since they inherit from :ref:`Reference`, resources are reference-counted and freed when no longer in use. They are also cached once loaded from disk, so that any further attempts to load a resource from a given path will return the same reference (all this in contrast to a :ref:`Node`, which is not reference-counted and can be instanced from disk as many times as desired). Resources can be saved externally on disk or bundled into another object, such as a :ref:`Node` or another resource. + +**Note:** In C#, resources will not be freed instantly after they are no longer in use. Instead, garbage collection will run periodically and will free resources that are no longer in use. This means that unused resources will linger on for a while before being removed. Tutorials --------- @@ -46,6 +48,8 @@ Methods +---------------------------------+------------------------------------------------------------------------------------------------------------------+ | :ref:`Resource` | :ref:`duplicate` **(** :ref:`bool` subresources=false **)** |const| | +---------------------------------+------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`emit_changed` **(** **)** | ++---------------------------------+------------------------------------------------------------------------------------------------------------------+ | :ref:`Node` | :ref:`get_local_scene` **(** **)** |const| | +---------------------------------+------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`get_rid` **(** **)** |const| | @@ -64,6 +68,8 @@ Signals Emitted whenever the resource changes. +**Note:** This signal is not emitted automatically for custom resources, which means that you need to create a setter and emit the signal yourself. + Property Descriptions --------------------- @@ -95,7 +101,7 @@ If ``true``, the resource will be made unique in each instance of its local scen | *Getter* | get_name() | +-----------+-----------------+ -The name of the resource. This is an optional identifier. +The name of the resource. This is an optional identifier. If :ref:`resource_name` is not empty, its value will be displayed to represent the current resource in the editor inspector. For built-in scripts, the :ref:`resource_name` will be displayed as the tab name in the script editor. ---- @@ -134,6 +140,24 @@ Duplicates the resource, returning a new resource. By default, sub-resources are ---- +.. _class_Resource_method_emit_changed: + +- void **emit_changed** **(** **)** + +Emits the :ref:`changed` signal. + +If external objects which depend on this resource should be updated, this method must be called manually whenever the state of this resource has changed (such as modification of properties). + +The method is equivalent to: + +:: + + emit_signal("changed") + +**Note:** This method is called automatically for built-in resources. + +---- + .. _class_Resource_method_get_local_scene: - :ref:`Node` **get_local_scene** **(** **)** |const| diff --git a/classes/class_resourceformatloader.rst b/classes/class_resourceformatloader.rst index af58172f6..e256620ab 100644 --- a/classes/class_resourceformatloader.rst +++ b/classes/class_resourceformatloader.rst @@ -20,7 +20,7 @@ Godot loads resources in the editor or in exported games using ResourceFormatLoa Extending this class allows you to define your own loader. Be sure to respect the documented return types and values. You should give it a global class name with ``class_name`` for it to be registered. Like built-in ResourceFormatLoaders, it will be called automatically when loading resources of its handled type(s). You may also implement a :ref:`ResourceFormatSaver`. -**Note:** You can also extend :ref:`EditorImportPlugin` if the resource type you need exists but Godot is unable to load its format. Choosing one way over another depends if the format is suitable or not for the final exported game. For example, it's better to import ``.png`` textures as ``.stex`` (:ref:`StreamTexture`) first, so they can be loaded with better efficiency on the graphics card. +**Note:** You can also extend :ref:`EditorImportPlugin` if the resource type you need exists but Godot is unable to load its format. Choosing one way over another depends on if the format is suitable or not for the final exported game. For example, it's better to import ``.png`` textures as ``.stex`` (:ref:`StreamTexture`) first, so they can be loaded with better efficiency on the graphics card. Methods ------- diff --git a/classes/class_resourceloader.rst b/classes/class_resourceloader.rst index 68252f485..1ae0f923d 100644 --- a/classes/class_resourceloader.rst +++ b/classes/class_resourceloader.rst @@ -20,7 +20,10 @@ Singleton used to load resource files from the filesystem. It uses the many :ref:`ResourceFormatLoader` classes registered in the engine (either built-in or from a plugin) to load files into memory and convert them to a format that can be used by the engine. -GDScript has a simplified :ref:`@GDScript.load` built-in method which can be used in most situations, leaving the use of ``ResourceLoader`` for more advanced scenarios. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/677 `_ Methods ------- @@ -98,11 +101,13 @@ Loads a resource at the given ``path``, caching the result for further access. The registered :ref:`ResourceFormatLoader`\ s are queried sequentially to find the first one which can handle the file's extension, and then attempt loading. If loading fails, the remaining ResourceFormatLoaders are also attempted. -An optional ``type_hint`` can be used to further specify the :ref:`Resource` type that should be handled by the :ref:`ResourceFormatLoader`. +An optional ``type_hint`` can be used to further specify the :ref:`Resource` type that should be handled by the :ref:`ResourceFormatLoader`. Anything that inherits from :ref:`Resource` can be used as a type hint, for example :ref:`Image`. If ``no_cache`` is ``true``, the resource cache will be bypassed and the resource will be loaded anew. Otherwise, the cached resource will be returned if it exists. -Returns an empty resource if no ResourceFormatLoader could handle the file. +Returns an empty resource if no :ref:`ResourceFormatLoader` could handle the file. + +GDScript has a simplified :ref:`@GDScript.load` built-in method which can be used in most situations, leaving the use of ``ResourceLoader`` for more advanced scenarios. ---- @@ -112,7 +117,7 @@ Returns an empty resource if no ResourceFormatLoader could handle the file. Starts loading a resource interactively. The returned :ref:`ResourceInteractiveLoader` object allows to load with high granularity, calling its :ref:`ResourceInteractiveLoader.poll` method successively to load chunks. -An optional ``type_hint`` can be used to further specify the :ref:`Resource` type that should be handled by the :ref:`ResourceFormatLoader`. +An optional ``type_hint`` can be used to further specify the :ref:`Resource` type that should be handled by the :ref:`ResourceFormatLoader`. Anything that inherits from :ref:`Resource` can be used as a type hint, for example :ref:`Image`. ---- diff --git a/classes/class_richtextlabel.rst b/classes/class_richtextlabel.rst index 498bd9d81..ea7fc730c 100644 --- a/classes/class_richtextlabel.rst +++ b/classes/class_richtextlabel.rst @@ -20,6 +20,8 @@ Rich text can contain custom text, fonts, images and some basic formatting. The **Note:** Assignments to :ref:`bbcode_text` clear the tag stack and reconstruct it from the property's contents. Any edits made to :ref:`bbcode_text` will erase previous edits made from other manual sources such as :ref:`append_bbcode` and the ``push_*`` / :ref:`pop` methods. +**Note:** RichTextLabel doesn't support entangled BBCode tags. For example, instead of using ``[b]bold[i]bold italic[/b]italic[/i]``, use ``[b]bold[i]bold italic[/i][/b][i]italic[/i]``. + **Note:** Unlike :ref:`Label`, RichTextLabel doesn't have a *property* to horizontally align text to the center. Instead, enable :ref:`bbcode_enabled` and surround the text in a ``[center]`` tag as follows: ``[center]Example[/center]``. There is currently no built-in way to vertically align text either, but this can be emulated by relying on anchors/containers and the :ref:`fit_content_height` property. Tutorials @@ -27,6 +29,10 @@ Tutorials - :doc:`../tutorials/gui/bbcode_in_richtextlabel` +- `https://godotengine.org/asset-library/asset/132 `_ + +- `https://godotengine.org/asset-library/asset/677 `_ + Properties ---------- @@ -333,6 +339,8 @@ Property Descriptions If ``true``, the label uses BBCode formatting. +**Note:** Trying to alter the ``RichTextLabel``'s text with :ref:`add_text` will reset this to ``false``. Use instead :ref:`append_bbcode` to preserve BBCode formatting. + ---- .. _class_RichTextLabel_property_bbcode_text: @@ -349,7 +357,7 @@ If ``true``, the label uses BBCode formatting. The label's text in BBCode format. Is not representative of manual modifications to the internal tag stack. Erases changes made by other methods when edited. -**Note:** It is unadvised to use ``+=`` operator with ``bbcode_text`` (e.g. ``bbcode_text += "some string"``) as it replaces the whole text and can cause slowdowns. Use :ref:`append_bbcode` for adding text instead. +**Note:** It is unadvised to use the ``+=`` operator with ``bbcode_text`` (e.g. ``bbcode_text += "some string"``) as it replaces the whole text and can cause slowdowns. Use :ref:`append_bbcode` for adding text instead, unless you absolutely need to close a tag that was opened in an earlier method call. ---- @@ -535,6 +543,8 @@ When set, clears the tag stack and adds a raw text tag to the top of it. Does no The restricted number of characters to display in the label. If ``-1``, all characters will be displayed. +**Note:** Setting this property updates :ref:`percent_visible` based on current :ref:`get_total_character_count`. + Method Descriptions ------------------- @@ -562,6 +572,8 @@ Adds raw non-BBCode-parsed text to the tag stack. Parses ``bbcode`` and adds tags to the tag stack as needed. Returns the result of the parsing, :ref:`@GlobalScope.OK` if successful. +**Note:** Using this method, you can't close a tag that was opened in a previous :ref:`append_bbcode` call. This is done to improve performance, especially when updating large RichTextLabels since rebuilding the whole BBCode every time would be slower. If you absolutely need to close a tag in a future method call, append the :ref:`bbcode_text` instead of using :ref:`append_bbcode`. + ---- .. _class_RichTextLabel_method_clear: diff --git a/classes/class_rigidbody.rst b/classes/class_rigidbody.rst index f1f052832..90cb68c0c 100644 --- a/classes/class_rigidbody.rst +++ b/classes/class_rigidbody.rst @@ -33,6 +33,10 @@ Tutorials - :doc:`../tutorials/physics/physics_introduction` +- `https://godotengine.org/asset-library/asset/524 `_ + +- `https://godotengine.org/asset-library/asset/675 `_ + Properties ---------- @@ -120,7 +124,9 @@ Signals - **body_entered** **(** :ref:`Node` body **)** -Emitted when a body enters into contact with this one. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. +Emitted when a collision with another :ref:`PhysicsBody` or :ref:`GridMap` occurs. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. :ref:`GridMap`\ s are detected if the :ref:`MeshLibrary` has Collision :ref:`Shape`\ s. + +``body`` the :ref:`Node`, if it exists in the tree, of the other :ref:`PhysicsBody` or :ref:`GridMap`. ---- @@ -128,7 +134,9 @@ Emitted when a body enters into contact with this one. Requires :ref:`contact_mo - **body_exited** **(** :ref:`Node` body **)** -Emitted when a body shape exits contact with this one. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. +Emitted when the collision with another :ref:`PhysicsBody` or :ref:`GridMap` ends. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. :ref:`GridMap`\ s are detected if the :ref:`MeshLibrary` has Collision :ref:`Shape`\ s. + +``body`` the :ref:`Node`, if it exists in the tree, of the other :ref:`PhysicsBody` or :ref:`GridMap`. ---- @@ -136,9 +144,17 @@ Emitted when a body shape exits contact with this one. Requires :ref:`contact_mo - **body_shape_entered** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` local_shape **)** -Emitted when a body enters into contact with this one. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. +Emitted when one of this RigidBody's :ref:`Shape`\ s collides with another :ref:`PhysicsBody` or :ref:`GridMap`'s :ref:`Shape`\ s. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. :ref:`GridMap`\ s are detected if the :ref:`MeshLibrary` has Collision :ref:`Shape`\ s. -This signal not only receives the body that collided with this one, but also its :ref:`RID` (``body_id``), the shape index from the colliding body (``body_shape``), and the shape index from this body (``local_shape``) the other body collided with. +``body_id`` the :ref:`RID` of the other :ref:`PhysicsBody` or :ref:`MeshLibrary`'s :ref:`CollisionObject` used by the :ref:`PhysicsServer`. + +``body`` the :ref:`Node`, if it exists in the tree, of the other :ref:`PhysicsBody` or :ref:`GridMap`. + +``body_shape`` the index of the :ref:`Shape` of the other :ref:`PhysicsBody` or :ref:`GridMap` used by the :ref:`PhysicsServer`. + +``local_shape`` the index of the :ref:`Shape` of this RigidBody used by the :ref:`PhysicsServer`. + +**Note:** Bullet physics cannot identify the shape index when using a :ref:`ConcavePolygonShape`. Don't use multiple :ref:`CollisionShape`\ s when using a :ref:`ConcavePolygonShape` with Bullet physics if you need shape indices. ---- @@ -146,9 +162,17 @@ This signal not only receives the body that collided with this one, but also its - **body_shape_exited** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` local_shape **)** -Emitted when a body shape exits contact with this one. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. +Emitted when the collision between one of this RigidBody's :ref:`Shape`\ s and another :ref:`PhysicsBody` or :ref:`GridMap`'s :ref:`Shape`\ s ends. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. :ref:`GridMap`\ s are detected if the :ref:`MeshLibrary` has Collision :ref:`Shape`\ s. -This signal not only receives the body that stopped colliding with this one, but also its :ref:`RID` (``body_id``), the shape index from the colliding body (``body_shape``), and the shape index from this body (``local_shape``) the other body stopped colliding with. +``body_id`` the :ref:`RID` of the other :ref:`PhysicsBody` or :ref:`MeshLibrary`'s :ref:`CollisionObject` used by the :ref:`PhysicsServer`. :ref:`GridMap`\ s are detected if the Meshes have :ref:`Shape`\ s. + +``body`` the :ref:`Node`, if it exists in the tree, of the other :ref:`PhysicsBody` or :ref:`GridMap`. + +``body_shape`` the index of the :ref:`Shape` of the other :ref:`PhysicsBody` or :ref:`GridMap` used by the :ref:`PhysicsServer`. + +``local_shape`` the index of the :ref:`Shape` of this RigidBody used by the :ref:`PhysicsServer`. + +**Note:** Bullet physics cannot identify the shape index when using a :ref:`ConcavePolygonShape`. Don't use multiple :ref:`CollisionShape`\ s when using a :ref:`ConcavePolygonShape` with Bullet physics if you need shape indices. ---- @@ -200,6 +224,8 @@ Property Descriptions Damps RigidBody's rotational forces. +See :ref:`ProjectSettings.physics/3d/default_angular_damp` for more details about damping. + ---- .. _class_RigidBody_property_angular_velocity: @@ -462,6 +488,8 @@ This is multiplied by the global 3D gravity setting found in **Project > Project The body's linear damp. Cannot be less than -1.0. If this value is different from -1.0, any linear damp derived from the world or areas will be overridden. +See :ref:`ProjectSettings.physics/3d/default_linear_damp` for more details about damping. + ---- .. _class_RigidBody_property_linear_velocity: diff --git a/classes/class_rigidbody2d.rst b/classes/class_rigidbody2d.rst index ce869000d..8923d5862 100644 --- a/classes/class_rigidbody2d.rst +++ b/classes/class_rigidbody2d.rst @@ -16,7 +16,7 @@ A body that is controlled by the 2D physics engine. Description ----------- -This node implements simulated 2D physics. You do not control a RigidBody2D directly. Instead you apply forces to it (gravity, impulses, etc.) and the physics simulation calculates the resulting movement based on its mass, friction, and other physical properties. +This node implements simulated 2D physics. You do not control a RigidBody2D directly. Instead, you apply forces to it (gravity, impulses, etc.) and the physics simulation calculates the resulting movement based on its mass, friction, and other physical properties. A RigidBody2D has 4 behavior :ref:`mode`\ s: Rigid, Static, Character, and Kinematic. @@ -28,6 +28,13 @@ If you need to override the default physics behavior or add a transformation at The center of mass is always located at the node's origin without taking into account the :ref:`CollisionShape2D` centroid offsets. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/119 `_ + +- `https://godotengine.org/asset-library/asset/148 `_ + Properties ---------- @@ -105,7 +112,9 @@ Signals - **body_entered** **(** :ref:`Node` body **)** -Emitted when a body enters into contact with this one. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. +Emitted when a collision with another :ref:`PhysicsBody2D` or :ref:`TileMap` occurs. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. :ref:`TileMap`\ s are detected if the :ref:`TileSet` has Collision :ref:`Shape2D`\ s. + +``body`` the :ref:`Node`, if it exists in the tree, of the other :ref:`PhysicsBody2D` or :ref:`TileMap`. ---- @@ -113,7 +122,9 @@ Emitted when a body enters into contact with this one. Requires :ref:`contact_mo - **body_exited** **(** :ref:`Node` body **)** -Emitted when a body exits contact with this one. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. +Emitted when the collision with another :ref:`PhysicsBody2D` or :ref:`TileMap` ends. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. :ref:`TileMap`\ s are detected if the :ref:`TileSet` has Collision :ref:`Shape2D`\ s. + +``body`` the :ref:`Node`, if it exists in the tree, of the other :ref:`PhysicsBody2D` or :ref:`TileMap`. ---- @@ -121,7 +132,15 @@ Emitted when a body exits contact with this one. Requires :ref:`contact_monitor< - **body_shape_entered** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` local_shape **)** -Emitted when a body enters into contact with this one. Reports colliding shape information. See :ref:`CollisionObject2D` for shape index information. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. +Emitted when one of this RigidBody2D's :ref:`Shape2D`\ s collides with another :ref:`PhysicsBody2D` or :ref:`TileMap`'s :ref:`Shape2D`\ s. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. :ref:`TileMap`\ s are detected if the :ref:`TileSet` has Collision :ref:`Shape2D`\ s. + +``body_id`` the :ref:`RID` of the other :ref:`PhysicsBody2D` or :ref:`TileSet`'s :ref:`CollisionObject2D` used by the :ref:`Physics2DServer`. + +``body`` the :ref:`Node`, if it exists in the tree, of the other :ref:`PhysicsBody2D` or :ref:`TileMap`. + +``body_shape`` the index of the :ref:`Shape2D` of the other :ref:`PhysicsBody2D` or :ref:`TileMap` used by the :ref:`Physics2DServer`. + +``local_shape`` the index of the :ref:`Shape2D` of this RigidBody2D used by the :ref:`Physics2DServer`. ---- @@ -129,7 +148,15 @@ Emitted when a body enters into contact with this one. Reports colliding shape i - **body_shape_exited** **(** :ref:`int` body_id, :ref:`Node` body, :ref:`int` body_shape, :ref:`int` local_shape **)** -Emitted when a body shape exits contact with this one. Reports colliding shape information. See :ref:`CollisionObject2D` for shape index information. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. +Emitted when the collision between one of this RigidBody2D's :ref:`Shape2D`\ s and another :ref:`PhysicsBody2D` or :ref:`TileMap`'s :ref:`Shape2D`\ s ends. Requires :ref:`contact_monitor` to be set to ``true`` and :ref:`contacts_reported` to be set high enough to detect all the collisions. :ref:`TileMap`\ s are detected if the :ref:`TileSet` has Collision :ref:`Shape2D`\ s. + +``body_id`` the :ref:`RID` of the other :ref:`PhysicsBody2D` or :ref:`TileSet`'s :ref:`CollisionObject2D` used by the :ref:`Physics2DServer`. + +``body`` the :ref:`Node`, if it exists in the tree, of the other :ref:`PhysicsBody2D` or :ref:`TileMap`. + +``body_shape`` the index of the :ref:`Shape2D` of the other :ref:`PhysicsBody2D` or :ref:`TileMap` used by the :ref:`Physics2DServer`. + +``local_shape`` the index of the :ref:`Shape2D` of this RigidBody2D used by the :ref:`Physics2DServer`. ---- @@ -199,6 +226,8 @@ Property Descriptions Damps the body's :ref:`angular_velocity`. If ``-1``, the body will use the **Default Angular Damp** defined in **Project > Project Settings > Physics > 2d**. +See :ref:`ProjectSettings.physics/2d/default_angular_damp` for more details about damping. + ---- .. _class_RigidBody2D_property_angular_velocity: @@ -313,7 +342,7 @@ If ``true``, the body will emit signals when it collides with another RigidBody2 The maximum number of contacts that will be recorded. Requires :ref:`contact_monitor` to be set to ``true``. -**Note:** The number of contacts is different from the number of collisions. Collisions between parallel edges will result in two contacts (one at each end), and collisions between parallel faces will result in four contacts (one at each corner). +**Note:** The number of contacts is different from the number of collisions. Collisions between parallel edges will result in two contacts (one at each end). ---- @@ -411,6 +440,8 @@ The body's moment of inertia. This is like mass, but for rotation: it determines Damps the body's :ref:`linear_velocity`. If ``-1``, the body will use the **Default Linear Damp** in **Project > Project Settings > Physics > 2d**. +See :ref:`ProjectSettings.physics/2d/default_linear_damp` for more details about damping. + ---- .. _class_RigidBody2D_property_linear_velocity: diff --git a/classes/class_scenetree.rst b/classes/class_scenetree.rst index 14b7b3922..f4c57033d 100644 --- a/classes/class_scenetree.rst +++ b/classes/class_scenetree.rst @@ -18,7 +18,7 @@ Description As one of the most important classes, the ``SceneTree`` manages the hierarchy of nodes in a scene as well as scenes themselves. Nodes can be added, retrieved and removed. The whole scene tree (and thus the current scene) can be paused. Scenes can be loaded, switched and reloaded. -You can also use the ``SceneTree`` to organize your nodes into groups: every node can be assigned as many groups as you want to create, e.g. a "enemy" group. You can then iterate these groups or even call methods and set properties on all the group's members at once. +You can also use the ``SceneTree`` to organize your nodes into groups: every node can be assigned as many groups as you want to create, e.g. an "enemy" group. You can then iterate these groups or even call methods and set properties on all the group's members at once. ``SceneTree`` is the default :ref:`MainLoop` implementation used by scenes, and is thus in charge of the game loop. @@ -479,7 +479,9 @@ Method Descriptions - :ref:`Variant` **call_group** **(** :ref:`String` group, :ref:`String` method, ... **)** |vararg| -Calls ``method`` on each member of the given group. +Calls ``method`` on each member of the given group. You can pass arguments to ``method`` by specifying them at the end of the method call. + +**Note:** ``method`` may only have 5 arguments at most (7 arguments passed to this method in total). ---- @@ -487,7 +489,9 @@ Calls ``method`` on each member of the given group. - :ref:`Variant` **call_group_flags** **(** :ref:`int` flags, :ref:`String` group, :ref:`String` method, ... **)** |vararg| -Calls ``method`` on each member of the given group, respecting the given :ref:`GroupCallFlags`. +Calls ``method`` on each member of the given group, respecting the given :ref:`GroupCallFlags`. You can pass arguments to ``method`` by specifying them at the end of the method call. + +**Note:** ``method`` may only have 5 arguments at most (8 arguments passed to this method in total). ---- @@ -499,6 +503,8 @@ Changes the running scene to the one at the given ``path``, after loading it int Returns :ref:`@GlobalScope.OK` on success, :ref:`@GlobalScope.ERR_CANT_OPEN` if the ``path`` cannot be loaded into a :ref:`PackedScene`, or :ref:`@GlobalScope.ERR_CANT_CREATE` if that scene cannot be instantiated. +**Note:** The scene change is deferred, which means that the new scene node is added on the next idle frame. You won't be able to access it immediately after the :ref:`change_scene` call. + ---- .. _class_SceneTree_method_change_scene_to: @@ -509,6 +515,8 @@ Changes the running scene to a new instance of the given :ref:`PackedScene` on success or :ref:`@GlobalScope.ERR_CANT_CREATE` if the scene cannot be instantiated. +**Note:** The scene change is deferred, which means that the new scene node is added on the next idle frame. You won't be able to access it immediately after the :ref:`change_scene_to` call. + ---- .. _class_SceneTree_method_create_timer: @@ -526,6 +534,8 @@ Commonly used to create a one-shot delay timer as in the following example: yield(get_tree().create_timer(1.0), "timeout") print("end") +The timer will be automatically freed after its time elapses. + ---- .. _class_SceneTree_method_get_frame: @@ -636,7 +646,7 @@ Queues the given object for deletion, delaying the call to :ref:`Object.free` exit_code=-1 **)** -Quits the application. A process ``exit_code`` can optionally be passed as an argument. If this argument is ``0`` or greater, it will override the :ref:`OS.exit_code` defined before quitting the application. +Quits the application at the end of the current iteration. A process ``exit_code`` can optionally be passed as an argument. If this argument is ``0`` or greater, it will override the :ref:`OS.exit_code` defined before quitting the application. ---- diff --git a/classes/class_scripteditor.rst b/classes/class_scripteditor.rst index b4e038b8a..0a9470a87 100644 --- a/classes/class_scripteditor.rst +++ b/classes/class_scripteditor.rst @@ -103,6 +103,8 @@ Goes to the specified line in the current script. - void **open_script_create_dialog** **(** :ref:`String` base_name, :ref:`String` base_path **)** +Opens the script create dialog. The script will extend ``base_name``. The file extension can be omitted from ``base_path``. It will be added based on the selected scripting language. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_shadermaterial.rst b/classes/class_shadermaterial.rst index 0256e4889..c9ee41203 100644 --- a/classes/class_shadermaterial.rst +++ b/classes/class_shadermaterial.rst @@ -18,6 +18,8 @@ Description A material that uses a custom :ref:`Shader` program to render either items to screen or process particles. You can create multiple materials for the same shader but configure different values for the uniforms defined in the shader. +**Note:** Due to a renderer limitation, emissive ``ShaderMaterial``\ s cannot emit light when used in a :ref:`GIProbe`. Only emissive :ref:`SpatialMaterial`\ s can emit light in a :ref:`GIProbe`. + Tutorials --------- diff --git a/classes/class_shape.rst b/classes/class_shape.rst index 5db420802..f776ab177 100644 --- a/classes/class_shape.rst +++ b/classes/class_shape.rst @@ -47,7 +47,9 @@ Property Descriptions | *Getter* | get_margin() | +-----------+-------------------+ -The collision margin for the shape. +The collision margin for the shape. Used in Bullet Physics only. + +Collision margins allow collision detection to be more efficient by adding an extra shell around shapes. Collision algorithms are more expensive when objects overlap by more than their margin, so a higher value for margins is better for performance, at the cost of accuracy around edges as it makes them less sharp. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_skeleton.rst b/classes/class_skeleton.rst index e38fdee9c..70704fade 100644 --- a/classes/class_skeleton.rst +++ b/classes/class_skeleton.rst @@ -22,6 +22,13 @@ The overall transform of a bone with respect to the skeleton is determined by th Note that "global pose" below refers to the overall transform of the bone with respect to skeleton, so it not the actual global/world transform of the bone. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/523 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + Methods ------- @@ -83,6 +90,13 @@ Methods | void | :ref:`unparent_bone_and_rest` **(** :ref:`int` bone_idx **)** | +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +Signals +------- + +.. _class_Skeleton_signal_skeleton_updated: + +- **skeleton_updated** **(** **)** + Constants --------- diff --git a/classes/class_skeletonik.rst b/classes/class_skeletonik.rst index 209cde896..2ea096dc2 100644 --- a/classes/class_skeletonik.rst +++ b/classes/class_skeletonik.rst @@ -13,6 +13,11 @@ SkeletonIK +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/523 `_ + Properties ---------- diff --git a/classes/class_sliderjoint.rst b/classes/class_sliderjoint.rst index b72cf99ba..516b3b202 100644 --- a/classes/class_sliderjoint.rst +++ b/classes/class_sliderjoint.rst @@ -11,12 +11,12 @@ SliderJoint **Inherits:** :ref:`Joint` **<** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` -Piston kind of slider between two bodies in 3D. +Slider between two PhysicsBodies in 3D. Description ----------- -Slides across the X axis of the pivot object. +Slides across the X axis of the pivot object. See also :ref:`Generic6DOFJoint`. Properties ---------- diff --git a/classes/class_softbody.rst b/classes/class_softbody.rst index 367499c45..e39eda63a 100644 --- a/classes/class_softbody.rst +++ b/classes/class_softbody.rst @@ -106,7 +106,7 @@ The physics layers this SoftBody is in. Collidable objects can exist in any of 32 different layers. These layers work like a tagging system, and are not visual. A collidable can use these layers to select with which objects it can collide, using the collision_mask property. -A contact is detected if object A is in any of the layers that object B scans, or object B is in any layer scanned by object A. See `Collision layers and masks `_ in the documentation for more information. +A contact is detected if object A is in any of the layers that object B scans, or object B is in any layer scanned by object A. See `Collision layers and masks `_ in the documentation for more information. ---- @@ -122,7 +122,7 @@ A contact is detected if object A is in any of the layers that object B scans, o | *Getter* | get_collision_mask() | +-----------+---------------------------+ -The physics layers this SoftBody scans for collisions. See `Collision layers and masks `_ in the documentation for more information. +The physics layers this SoftBody scans for collisions. See `Collision layers and masks `_ in the documentation for more information. ---- diff --git a/classes/class_spatial.rst b/classes/class_spatial.rst index c240a6e14..226078c44 100644 --- a/classes/class_spatial.rst +++ b/classes/class_spatial.rst @@ -29,6 +29,8 @@ Tutorials - :doc:`../tutorials/3d/introduction_to_3d` +- `https://github.com/godotengine/godot-demo-projects/tree/master/3d `_ + Properties ---------- @@ -143,7 +145,7 @@ Constants - **NOTIFICATION_TRANSFORM_CHANGED** = **2000** --- Spatial nodes receives this notification when their global transform changes. This means that either the current or a parent node changed its transform. -In order for :ref:`NOTIFICATION_TRANSFORM_CHANGED` to work, users first need to ask for it, with :ref:`set_notify_transform`. +In order for :ref:`NOTIFICATION_TRANSFORM_CHANGED` to work, users first need to ask for it, with :ref:`set_notify_transform`. The notification is also sent if the node is in the editor context and it has a valid gizmo. - **NOTIFICATION_ENTER_WORLD** = **41** --- Spatial nodes receives this notification when they are registered to new :ref:`World` resource. @@ -495,7 +497,7 @@ Sets whether the node notifies about its local transformation changes. ``Spatial - void **set_notify_transform** **(** :ref:`bool` enable **)** -Sets whether the node notifies about its global and local transformation changes. ``Spatial`` will not propagate this by default. +Sets whether the node notifies about its global and local transformation changes. ``Spatial`` will not propagate this by default, unless it is in the editor context and it has a valid gizmo. ---- diff --git a/classes/class_spatialmaterial.rst b/classes/class_spatialmaterial.rst index 81a2067c6..c0bf77eb7 100644 --- a/classes/class_spatialmaterial.rst +++ b/classes/class_spatialmaterial.rst @@ -915,6 +915,8 @@ If ``true``, the shader will read depth texture at multiple points along the vie If ``true``, depth mapping is enabled (also called "parallax mapping" or "height mapping"). See also :ref:`normal_enabled`. +**Note:** Depth mapping is not supported if triplanar mapping is used on the same material. The value of :ref:`depth_enabled` will be ignored if :ref:`uv1_triplanar` is enabled. + ---- .. _class_SpatialMaterial_property_depth_flip_binormal: @@ -1099,7 +1101,9 @@ Specifies whether to use ``UV`` or ``UV2`` for the detail layer. See :ref:`Detai | *Getter* | get_distance_fade_max_distance() | +----------+---------------------------------------+ -Distance at which the object fades fully and is no longer visible. +Distance at which the object appears fully opaque. + +**Note:** If ``distance_fade_max_distance`` is less than ``distance_fade_min_distance``, the behavior will be reversed. The object will start to fade away at ``distance_fade_max_distance`` and will fully disappear once it reaches ``distance_fade_min_distance``. ---- @@ -1113,7 +1117,9 @@ Distance at which the object fades fully and is no longer visible. | *Getter* | get_distance_fade_min_distance() | +----------+---------------------------------------+ -Distance at which the object starts to fade. If the object is less than this distance away it will appear normal. +Distance at which the object starts to become visible. If the object is less than this distance away, it will be invisible. + +**Note:** If ``distance_fade_min_distance`` is greater than ``distance_fade_max_distance``, the behavior will be reversed. The object will start to fade away at ``distance_fade_max_distance`` and will fully disappear once it reaches ``distance_fade_min_distance``. ---- @@ -1567,6 +1573,8 @@ If ``true``, the shader will keep the scale set for the mesh. Otherwise the scal Controls how the object faces the camera. See :ref:`BillboardMode`. +**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. + ---- .. _class_SpatialMaterial_property_params_blend_mode: diff --git a/classes/class_sphereshape.rst b/classes/class_sphereshape.rst index e498698af..cdad340d6 100644 --- a/classes/class_sphereshape.rst +++ b/classes/class_sphereshape.rst @@ -18,6 +18,11 @@ Description Sphere shape for 3D collisions, which can be set into a :ref:`PhysicsBody` or :ref:`Area`. This shape is useful for modeling sphere-like 3D objects. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/675 `_ + Properties ---------- diff --git a/classes/class_spinbox.rst b/classes/class_spinbox.rst index d3d8cddd4..38311ba2d 100644 --- a/classes/class_spinbox.rst +++ b/classes/class_spinbox.rst @@ -32,6 +32,8 @@ The above code will create a ``SpinBox``, disable context menu on it and set the See :ref:`Range` class for more options over the ``SpinBox``. +**Note:** ``SpinBox`` relies on an underlying :ref:`LineEdit` node. To theme a ``SpinBox``'s background, add theme items for :ref:`LineEdit` and customize them. + Properties ---------- diff --git a/classes/class_spotlight.rst b/classes/class_spotlight.rst index 2a60c6d12..fc231abb0 100644 --- a/classes/class_spotlight.rst +++ b/classes/class_spotlight.rst @@ -18,11 +18,15 @@ Description A Spotlight is a type of :ref:`Light` node that emits lights in a specific direction, in the shape of a cone. The light is attenuated through the distance. This attenuation can be configured by changing the energy, radius and attenuation parameters of :ref:`Light`. +**Note:** By default, only 32 SpotLights may affect a single mesh *resource* at once. Consider splitting your level into several meshes to decrease the likelihood that more than 32 lights will affect the same mesh resource. Splitting the level mesh will also improve frustum culling effectiveness, leading to greater performance. If you need to use more lights per mesh, you can increase :ref:`ProjectSettings.rendering/limits/rendering/max_lights_per_object` at the cost of shader compilation times. + Tutorials --------- - :doc:`../tutorials/3d/lights_and_shadows` +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ---------- diff --git a/classes/class_springarm.rst b/classes/class_springarm.rst index 5d37d0d9c..87cdc32ed 100644 --- a/classes/class_springarm.rst +++ b/classes/class_springarm.rst @@ -65,7 +65,7 @@ Property Descriptions | *Getter* | get_collision_mask() | +-----------+---------------------------+ -The layers against which the collision check shall be done. See `Collision layers and masks `_ in the documentation for more information. +The layers against which the collision check shall be done. See `Collision layers and masks `_ in the documentation for more information. ---- diff --git a/classes/class_sprite.rst b/classes/class_sprite.rst index bf6ea63e5..876e2a922 100644 --- a/classes/class_sprite.rst +++ b/classes/class_sprite.rst @@ -18,6 +18,11 @@ Description A node that displays a 2D texture. The texture displayed can be a region from a larger atlas texture, or a frame from a sprite sheet animation. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/148 `_ + Properties ---------- @@ -138,7 +143,7 @@ If ``true``, texture is flipped vertically. | *Getter* | get_frame() | +-----------+------------------+ -Current frame to display from sprite sheet. :ref:`vframes` or :ref:`hframes` must be greater than 1. +Current frame to display from sprite sheet. :ref:`hframes` or :ref:`vframes` must be greater than 1. ---- @@ -154,7 +159,7 @@ Current frame to display from sprite sheet. :ref:`vframes` property. :ref:`vframes` or :ref:`hframes` must be greater than 1. +Coordinates of the frame to display from sprite sheet. This is as an alias for the :ref:`frame` property. :ref:`hframes` or :ref:`vframes` must be greater than 1. ---- diff --git a/classes/class_sprite3d.rst b/classes/class_sprite3d.rst index 024eab7dd..7253c79db 100644 --- a/classes/class_sprite3d.rst +++ b/classes/class_sprite3d.rst @@ -61,7 +61,7 @@ Property Descriptions | *Getter* | get_frame() | +-----------+------------------+ -Current frame to display from sprite sheet. :ref:`vframes` or :ref:`hframes` must be greater than 1. +Current frame to display from sprite sheet. :ref:`hframes` or :ref:`vframes` must be greater than 1. ---- @@ -77,7 +77,7 @@ Current frame to display from sprite sheet. :ref:`vframes` property. :ref:`vframes` or :ref:`hframes` must be greater than 1. +Coordinates of the frame to display from sprite sheet. This is as an alias for the :ref:`frame` property. :ref:`hframes` or :ref:`vframes` must be greater than 1. ---- diff --git a/classes/class_spritebase3d.rst b/classes/class_spritebase3d.rst index 88e41322e..8ed11d2e0 100644 --- a/classes/class_spritebase3d.rst +++ b/classes/class_spritebase3d.rst @@ -260,7 +260,7 @@ The texture's drawing offset. | *Getter* | get_opacity() | +-----------+--------------------+ -The objects visibility on a scale from ``0`` fully invisible to ``1`` fully visible. +The objects' visibility on a scale from ``0`` fully invisible to ``1`` fully visible. ---- diff --git a/classes/class_staticbody.rst b/classes/class_staticbody.rst index 064414655..983fb2bfd 100644 --- a/classes/class_staticbody.rst +++ b/classes/class_staticbody.rst @@ -20,6 +20,15 @@ Static body for 3D physics. A static body is a simple body that is not intended Additionally, a constant linear or angular velocity can be set for the static body, so even if it doesn't move, it affects other bodies as if it was moving (this is useful for simulating conveyor belts or conveyor wheels). +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/675 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + +- `https://godotengine.org/asset-library/asset/676 `_ + Properties ---------- diff --git a/classes/class_streampeertcp.rst b/classes/class_streampeertcp.rst index a2cafa982..b68626e04 100644 --- a/classes/class_streampeertcp.rst +++ b/classes/class_streampeertcp.rst @@ -107,7 +107,7 @@ Returns the status of the connection, see :ref:`Status` **is_connected_to_host** **(** **)** |const| -Returns ``true`` if this peer is currently connected to a host, ``false`` otherwise. +Returns ``true`` if this peer is currently connected or is connecting to a host, ``false`` otherwise. ---- diff --git a/classes/class_string.rst b/classes/class_string.rst index 75cca843f..fa57d1f16 100644 --- a/classes/class_string.rst +++ b/classes/class_string.rst @@ -163,6 +163,8 @@ Methods +-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`md5_text` **(** **)** | +-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`naturalnocasecmp_to` **(** :ref:`String` to **)** | ++-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`nocasecmp_to` **(** :ref:`String` to **)** | +-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`ord_at` **(** :ref:`int` at **)** | @@ -225,10 +227,14 @@ Methods +-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PoolByteArray` | :ref:`to_utf8` **(** **)** | +-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PoolByteArray` | :ref:`to_wchar` **(** **)** | ++-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`trim_prefix` **(** :ref:`String` prefix **)** | +-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`trim_suffix` **(** :ref:`String` suffix **)** | +-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`validate_node_name` **(** **)** | ++-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`xml_escape` **(** **)** | +-----------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`xml_unescape` **(** **)** | @@ -429,7 +435,13 @@ Changes the case of some letters. Replaces underscores with spaces, adds spaces - :ref:`int` **casecmp_to** **(** :ref:`String` to **)** -Performs a case-sensitive comparison to another string. Returns ``-1`` if less than, ``+1`` if greater than, or ``0`` if equal. +Performs a case-sensitive comparison to another string. Returns ``-1`` if less than, ``1`` if greater than, or ``0`` if equal. "less than" or "greater than" are determined by the `Unicode code points`` of each string, which roughly matches the alphabetical order. + +**Behavior with different string lengths:** Returns ``1`` if the "base" string is longer than the ``to`` string or ``-1`` if the "base" string is shorter than the ``to`` string. Keep in mind this length is determined by the number of Unicode codepoints, *not* the actual visible characters. + +**Behavior with empty strings:** Returns ``-1`` if the "base" string is empty, ``1`` if the ``to`` string is empty or ``0`` if both strings are empty. + +To get a boolean result from a string comparison, use the ``==`` operator instead. See also :ref:`nocasecmp_to`. ---- @@ -705,7 +717,7 @@ Returns ``true`` if this string contains a valid integer. - :ref:`bool` **is_valid_ip_address** **(** **)** -Returns ``true`` if this string contains a valid IP address. +Returns ``true`` if this string contains only a well-formatted IPv4 or IPv6 address. This method considers `reserved IP addresses `_ such as ``0.0.0.0`` as valid. ---- @@ -737,7 +749,9 @@ Returns the string's amount of characters. - :ref:`String` **lstrip** **(** :ref:`String` chars **)** -Returns a copy of the string with characters removed from the left. +Returns a copy of the string with characters removed from the left. The ``chars`` argument is a string specifying the set of characters to be removed. + +**Note:** The ``chars`` is not a prefix. See :ref:`trim_prefix` method that will remove a single prefix string rather than a set of characters. ---- @@ -773,11 +787,33 @@ Returns the MD5 hash of the string as a string. ---- +.. _class_String_method_naturalnocasecmp_to: + +- :ref:`int` **naturalnocasecmp_to** **(** :ref:`String` to **)** + +Performs a case-insensitive *natural order* comparison to another string. Returns ``-1`` if less than, ``1`` if greater than, or ``0`` if equal. "less than" or "greater than" are determined by the `Unicode code points`` of each string, which roughly matches the alphabetical order. Internally, lowercase characters will be converted to uppercase during the comparison. + +When used for sorting, natural order comparison will order suites of numbers as expected by most people. If you sort the numbers from 1 to 10 using natural order, you will get ``[1, 2, 3, ...]`` instead of ``[1, 10, 2, 3, ...]``. + +**Behavior with different string lengths:** Returns ``1`` if the "base" string is longer than the ``to`` string or ``-1`` if the "base" string is shorter than the ``to`` string. Keep in mind this length is determined by the number of Unicode codepoints, *not* the actual visible characters. + +**Behavior with empty strings:** Returns ``-1`` if the "base" string is empty, ``1`` if the ``to`` string is empty or ``0`` if both strings are empty. + +To get a boolean result from a string comparison, use the ``==`` operator instead. See also :ref:`nocasecmp_to` and :ref:`casecmp_to`. + +---- + .. _class_String_method_nocasecmp_to: - :ref:`int` **nocasecmp_to** **(** :ref:`String` to **)** -Performs a case-insensitive comparison to another string. Returns ``-1`` if less than, ``+1`` if greater than, or ``0`` if equal. +Performs a case-insensitive comparison to another string. Returns ``-1`` if less than, ``1`` if greater than, or ``0`` if equal. "less than" or "greater than" are determined by the `Unicode code points`` of each string, which roughly matches the alphabetical order. Internally, lowercase characters will be converted to uppercase during the comparison. + +**Behavior with different string lengths:** Returns ``1`` if the "base" string is longer than the ``to`` string or ``-1`` if the "base" string is shorter than the ``to`` string. Keep in mind this length is determined by the number of Unicode codepoints, *not* the actual visible characters. + +**Behavior with empty strings:** Returns ``-1`` if the "base" string is empty, ``1`` if the ``to`` string is empty or ``0`` if both strings are empty. + +To get a boolean result from a string comparison, use the ``==`` operator instead. See also :ref:`casecmp_to`. ---- @@ -903,7 +939,9 @@ Example: - :ref:`String` **rstrip** **(** :ref:`String` chars **)** -Returns a copy of the string with characters removed from the right. +Returns a copy of the string with characters removed from the right. The ``chars`` argument is a string specifying the set of characters to be removed. + +**Note:** The ``chars`` is not a suffix. See :ref:`trim_suffix` method that will remove a single suffix string rather than a set of characters. ---- @@ -1051,6 +1089,14 @@ Converts the String (which is an array of characters) to :ref:`PoolByteArray` **to_wchar** **(** **)** + +Converts the String (which is an array of characters) to :ref:`PoolByteArray` (which is an array of bytes). + +---- + .. _class_String_method_trim_prefix: - :ref:`String` **trim_prefix** **(** :ref:`String` prefix **)** @@ -1067,6 +1113,14 @@ Removes a given string from the end if it ends with it or leaves the string unch ---- +.. _class_String_method_validate_node_name: + +- :ref:`String` **validate_node_name** **(** **)** + +Removes any characters from the string that are prohibited in :ref:`Node` names (``.`` ``:`` ``@`` ``/`` ``"``). + +---- + .. _class_String_method_xml_escape: - :ref:`String` **xml_escape** **(** **)** diff --git a/classes/class_stylebox.rst b/classes/class_stylebox.rst index 5223e5252..ff1202328 100644 --- a/classes/class_stylebox.rst +++ b/classes/class_stylebox.rst @@ -20,6 +20,8 @@ Description StyleBox is :ref:`Resource` that provides an abstract base class for drawing stylized boxes for the UI. StyleBoxes are used for drawing the styles of buttons, line edit backgrounds, tree backgrounds, etc. and also for testing a transparency mask for pointer signals. If mask test fails on a StyleBox assigned as mask to a control, clicks and motion signals will go through it to the one below. +**Note:** For children of :ref:`Control` that have *Theme Properties*, the ``focus`` ``StyleBox`` is displayed over the ``normal``, ``hover`` or ``pressed`` ``StyleBox``. This makes the ``focus`` ``StyleBox`` more reusable across different nodes. + Properties ---------- diff --git a/classes/class_styleboxflat.rst b/classes/class_styleboxflat.rst index f64f5fa20..d42256ce5 100644 --- a/classes/class_styleboxflat.rst +++ b/classes/class_styleboxflat.rst @@ -16,7 +16,7 @@ Customizable :ref:`StyleBox` with a given set of parameters (no Description ----------- -This :ref:`StyleBox` can be used to achieve all kinds of looks without the need of a texture. Those properties are customizable: +This :ref:`StyleBox` can be used to achieve all kinds of looks without the need of a texture. The following properties are customizable: - Color @@ -26,7 +26,7 @@ This :ref:`StyleBox` can be used to achieve all kinds of looks w - Shadow (with blur and offset) -Setting corner radius to high values is allowed. As soon as corners would overlap, the stylebox will switch to a relative system. Example: +Setting corner radius to high values is allowed. As soon as corners overlap, the stylebox will switch to a relative system. Example: :: @@ -278,9 +278,9 @@ Border width for the top border. | *Getter* | get_corner_detail() | +-----------+--------------------------+ -This sets the amount of vertices used for each corner. Higher values result in rounder corners but take more processing power to compute. When choosing a value, you should take the corner radius (:ref:`set_corner_radius_all`) into account. +This sets the number of vertices used for each corner. Higher values result in rounder corners but take more processing power to compute. When choosing a value, you should take the corner radius (:ref:`set_corner_radius_all`) into account. -For corner radii smaller than 10, ``4`` or ``5`` should be enough. For corner radii smaller than 30, values between ``8`` and ``12`` should be enough. +For corner radii less than 10, ``4`` or ``5`` should be enough. For corner radii less than 30, values between ``8`` and ``12`` should be enough. A corner detail of ``1`` will result in chamfered corners instead of rounded corners, which is useful for some artistic effects. diff --git a/classes/class_surfacetool.rst b/classes/class_surfacetool.rst index c199a34bd..3f6750e3e 100644 --- a/classes/class_surfacetool.rst +++ b/classes/class_surfacetool.rst @@ -36,6 +36,11 @@ See also :ref:`ArrayMesh`, :ref:`ImmediateGeometry`_ for front faces of triangle primitive modes. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/676 `_ + Methods ------- @@ -94,7 +99,7 @@ Method Descriptions - void **add_bones** **(** :ref:`PoolIntArray` bones **)** -Adds an array of bones for the next vertex to use. ``bones`` must contain 4 integers. +Specifies an array of bones to use for the *next* vertex. ``bones`` must contain 4 integers. ---- @@ -102,7 +107,9 @@ Adds an array of bones for the next vertex to use. ``bones`` must contain 4 inte - void **add_color** **(** :ref:`Color` color **)** -Specifies a :ref:`Color` for the next vertex to use. +Specifies a :ref:`Color` to use for the *next* vertex. If every vertex needs to have this information set and you fail to submit it for the first vertex, this information may not be used at all. + +**Note:** The material must have :ref:`SpatialMaterial.vertex_color_use_as_albedo` enabled for the vertex color to be visible. ---- @@ -118,7 +125,7 @@ Adds an index to index array if you are using indexed vertices. Does not need to - void **add_normal** **(** :ref:`Vector3` normal **)** -Specifies a normal for the next vertex to use. +Specifies a normal to use for the *next* vertex. If every vertex needs to have this information set and you fail to submit it for the first vertex, this information may not be used at all. ---- @@ -134,7 +141,7 @@ Specifies whether the current vertex (if using only vertex arrays) or current in - void **add_tangent** **(** :ref:`Plane` tangent **)** -Specifies a tangent for the next vertex to use. +Specifies a tangent to use for the *next* vertex. If every vertex needs to have this information set and you fail to submit it for the first vertex, this information may not be used at all. ---- @@ -152,7 +159,7 @@ Requires the primitive type be set to :ref:`Mesh.PRIMITIVE_TRIANGLES` uv **)** -Specifies a set of UV coordinates to use for the next vertex. +Specifies a set of UV coordinates to use for the *next* vertex. If every vertex needs to have this information set and you fail to submit it for the first vertex, this information may not be used at all. ---- @@ -160,7 +167,7 @@ Specifies a set of UV coordinates to use for the next vertex. - void **add_uv2** **(** :ref:`Vector2` uv2 **)** -Specifies an optional second set of UV coordinates to use for the next vertex. +Specifies an optional second set of UV coordinates to use for the *next* vertex. If every vertex needs to have this information set and you fail to submit it for the first vertex, this information may not be used at all. ---- @@ -176,7 +183,7 @@ Specifies the position of current vertex. Should be called after specifying othe - void **add_weights** **(** :ref:`PoolRealArray` weights **)** -Specifies weight values for next vertex to use. ``weights`` must contain 4 values. +Specifies weight values to use for the *next* vertex. ``weights`` must contain 4 values. If every vertex needs to have this information set and you fail to submit it for the first vertex, this information may not be used at all. ---- @@ -250,9 +257,9 @@ Removes the index array by expanding the vertex array. - void **generate_normals** **(** :ref:`bool` flip=false **)** -Generates normals from vertices so you do not have to do it manually. If ``flip`` is ``true``, the resulting normals will be inverted. +Generates normals from vertices so you do not have to do it manually. If ``flip`` is ``true``, the resulting normals will be inverted. :ref:`generate_normals` should be called *after* generating geometry and *before* committing the mesh using :ref:`commit` or :ref:`commit_to_arrays`. -Requires the primitive type to be set to :ref:`Mesh.PRIMITIVE_TRIANGLES`. +**Note:** :ref:`generate_normals` only works if the primitive type to be set to :ref:`Mesh.PRIMITIVE_TRIANGLES`. ---- @@ -268,7 +275,7 @@ Generates a tangent vector for each vertex. Requires that each vertex have UVs a - void **index** **(** **)** -Shrinks the vertex array by creating an index array (avoids reusing vertices). +Shrinks the vertex array by creating an index array. This can improve performance by avoiding vertex reuse. ---- diff --git a/classes/class_tabcontainer.rst b/classes/class_tabcontainer.rst index 92958f8e4..9e28d3450 100644 --- a/classes/class_tabcontainer.rst +++ b/classes/class_tabcontainer.rst @@ -27,6 +27,8 @@ To hide only a tab's content, nest the content inside a child :ref:`Control` | :ref:`all_tabs_in_front` | ``false`` | +---------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ | :ref:`int` | :ref:`current_tab` | ``0`` | +---------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ @@ -162,6 +164,22 @@ enum **TabAlign**: Property Descriptions --------------------- +.. _class_TabContainer_property_all_tabs_in_front: + +- :ref:`bool` **all_tabs_in_front** + ++-----------+------------------------------+ +| *Default* | ``false`` | ++-----------+------------------------------+ +| *Setter* | set_all_tabs_in_front(value) | ++-----------+------------------------------+ +| *Getter* | is_all_tabs_in_front() | ++-----------+------------------------------+ + +If ``true``, all tabs are drawn in front of the panel. If ``false``, inactive tabs are drawn behind the panel. + +---- + .. _class_TabContainer_property_current_tab: - :ref:`int` **current_tab** diff --git a/classes/class_tabs.rst b/classes/class_tabs.rst index 8aa4183fd..dd57003c1 100644 --- a/classes/class_tabs.rst +++ b/classes/class_tabs.rst @@ -16,7 +16,7 @@ Tabs control. Description ----------- -Simple tabs control, similar to :ref:`TabContainer` but is only in charge of drawing tabs, not interact with children. +Simple tabs control, similar to :ref:`TabContainer` but is only in charge of drawing tabs, not interacting with children. Properties ---------- @@ -43,6 +43,8 @@ Methods +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`get_offset_buttons_visible` **(** **)** |const| | +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_previous_tab` **(** **)** |const| | ++-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`get_select_with_rmb` **(** **)** |const| | +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_tab_count` **(** **)** |const| | @@ -258,7 +260,7 @@ If ``true``, tabs can be rearranged with mouse drag. | *Getter* | get_scrolling_enabled() | +-----------+------------------------------+ -if ``true``, the mouse's scroll wheel cab be used to navigate the scroll view. +if ``true``, the mouse's scroll wheel can be used to navigate the scroll view. ---- @@ -319,6 +321,14 @@ Returns ``true`` if the offset buttons (the ones that appear when there's not en ---- +.. _class_Tabs_method_get_previous_tab: + +- :ref:`int` **get_previous_tab** **(** **)** |const| + +Returns the previously active tab index. + +---- + .. _class_Tabs_method_get_select_with_rmb: - :ref:`bool` **get_select_with_rmb** **(** **)** |const| diff --git a/classes/class_textedit.rst b/classes/class_textedit.rst index 96e83ffe0..e9560db85 100644 --- a/classes/class_textedit.rst +++ b/classes/class_textedit.rst @@ -145,6 +145,12 @@ Methods +-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_line_hidden` **(** :ref:`int` line **)** |const| | +-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`is_line_set_as_bookmark` **(** :ref:`int` line **)** |const| | ++-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`is_line_set_as_breakpoint` **(** :ref:`int` line **)** |const| | ++-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`is_line_set_as_safe` **(** :ref:`int` line **)** |const| | ++-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_selection_active` **(** **)** |const| | +-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`menu_option` **(** :ref:`int` option **)** | @@ -163,8 +169,14 @@ Methods +-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_line` **(** :ref:`int` line, :ref:`String` new_text **)** | +-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_line_as_bookmark` **(** :ref:`int` line, :ref:`bool` bookmark **)** | ++-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_line_as_breakpoint` **(** :ref:`int` line, :ref:`bool` breakpoint **)** | ++-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_line_as_hidden` **(** :ref:`int` line, :ref:`bool` enable **)** | +-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_line_as_safe` **(** :ref:`int` line, :ref:`bool` safe **)** | ++-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`toggle_fold_line` **(** :ref:`int` line **)** | +-----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`undo` **(** **)** | @@ -1025,7 +1037,7 @@ Returns the selection end line. - :ref:`String` **get_word_under_cursor** **(** **)** |const| -Returns a :ref:`String` text with the word under the mouse cursor location. +Returns a :ref:`String` text with the word under the caret (text cursor) location. ---- @@ -1061,6 +1073,30 @@ Returns whether the line at the specified index is hidden or not. ---- +.. _class_TextEdit_method_is_line_set_as_bookmark: + +- :ref:`bool` **is_line_set_as_bookmark** **(** :ref:`int` line **)** |const| + +Returns ``true`` when the specified ``line`` is bookmarked. + +---- + +.. _class_TextEdit_method_is_line_set_as_breakpoint: + +- :ref:`bool` **is_line_set_as_breakpoint** **(** :ref:`int` line **)** |const| + +Returns ``true`` when the specified ``line`` has a breakpoint. + +---- + +.. _class_TextEdit_method_is_line_set_as_safe: + +- :ref:`bool` **is_line_set_as_safe** **(** :ref:`int` line **)** |const| + +Returns ``true`` when the specified ``line`` is marked as safe. + +---- + .. _class_TextEdit_method_is_selection_active: - :ref:`bool` **is_selection_active** **(** **)** |const| @@ -1147,6 +1183,24 @@ Sets the text for a specific line. ---- +.. _class_TextEdit_method_set_line_as_bookmark: + +- void **set_line_as_bookmark** **(** :ref:`int` line, :ref:`bool` bookmark **)** + +Bookmarks the ``line`` if ``bookmark`` is true. Deletes the bookmark if ``bookmark`` is false. + +Bookmarks are shown in the :ref:`breakpoint_gutter`. + +---- + +.. _class_TextEdit_method_set_line_as_breakpoint: + +- void **set_line_as_breakpoint** **(** :ref:`int` line, :ref:`bool` breakpoint **)** + +Adds or removes the breakpoint in ``line``. Breakpoints are shown in the :ref:`breakpoint_gutter`. + +---- + .. _class_TextEdit_method_set_line_as_hidden: - void **set_line_as_hidden** **(** :ref:`int` line, :ref:`bool` enable **)** @@ -1155,6 +1209,16 @@ If ``true``, hides the line of the specified index. ---- +.. _class_TextEdit_method_set_line_as_safe: + +- void **set_line_as_safe** **(** :ref:`int` line, :ref:`bool` safe **)** + +If ``true``, marks the ``line`` as safe. + +This will show the line number with the color provided in the ``safe_line_number_color`` theme property. + +---- + .. _class_TextEdit_method_toggle_fold_line: - void **toggle_fold_line** **(** :ref:`int` line **)** diff --git a/classes/class_texture.rst b/classes/class_texture.rst index da4e338ad..03953ea9e 100644 --- a/classes/class_texture.rst +++ b/classes/class_texture.rst @@ -24,6 +24,8 @@ Textures are often created by loading them from a file. See :ref:`@GDScript.load ``Texture`` is a base for other resources. It cannot be used directly. +**Note:** The maximum texture size is 16384×16384 pixels due to graphics hardware limitations. Larger textures may fail to import. + Properties ---------- @@ -81,6 +83,8 @@ enum **Flags**: - **FLAG_REPEAT** = **2** --- Repeats the texture (instead of clamp to edge). +**Note:** Ignored when using an :ref:`AtlasTexture` as these don't support repetition. + - **FLAG_FILTER** = **4** --- Uses a magnifying filter, to enable smooth zooming in of the texture. - **FLAG_ANISOTROPIC_FILTER** = **8** --- Uses anisotropic mipmap filtering. Generates smaller versions of the same texture with different aspect ratios. @@ -91,6 +95,8 @@ This results in better-looking textures when viewed from oblique angles. - **FLAG_MIRRORED_REPEAT** = **32** --- Repeats the texture with alternate sections mirrored. +**Note:** Ignored when using an :ref:`AtlasTexture` as these don't support repetition. + - **FLAG_VIDEO_SURFACE** = **2048** --- Texture is a video surface. Property Descriptions diff --git a/classes/class_texturebutton.rst b/classes/class_texturebutton.rst index faed03d61..a0d5ab4cd 100644 --- a/classes/class_texturebutton.rst +++ b/classes/class_texturebutton.rst @@ -20,6 +20,13 @@ Description The "normal" state must contain a texture (:ref:`texture_normal`); other textures are optional. +See also :ref:`BaseButton` which contains common properties and methods associated with this node. + +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/676 `_ + Properties ---------- diff --git a/classes/class_texturelayered.rst b/classes/class_texturelayered.rst index 977e17227..8789cf8fd 100644 --- a/classes/class_texturelayered.rst +++ b/classes/class_texturelayered.rst @@ -18,7 +18,7 @@ Base class for 3D texture types. Description ----------- -Base class for :ref:`Texture3D` and :ref:`TextureArray`. Cannot be used directly, but contains all the functions necessary for accessing and using :ref:`Texture3D` and :ref:`TextureArray`. Data is set on a per-layer basis. For :ref:`Texture3D`\ s, the layer sepcifies the depth or Z-index, they can be treated as a bunch of 2D slices. Similarly, for :ref:`TextureArray`\ s, the layer specifies the array layer. +Base class for :ref:`Texture3D` and :ref:`TextureArray`. Cannot be used directly, but contains all the functions necessary for accessing and using :ref:`Texture3D` and :ref:`TextureArray`. Data is set on a per-layer basis. For :ref:`Texture3D`\ s, the layer specifies the depth or Z-index, they can be treated as a bunch of 2D slices. Similarly, for :ref:`TextureArray`\ s, the layer specifies the array layer. Properties ---------- diff --git a/classes/class_texturerect.rst b/classes/class_texturerect.rst index 316cd77df..571af67bf 100644 --- a/classes/class_texturerect.rst +++ b/classes/class_texturerect.rst @@ -20,6 +20,11 @@ Used to draw icons and sprites in a user interface. The texture's placement can **Note:** You should enable :ref:`flip_v` when using a TextureRect to display a :ref:`ViewportTexture`. Alternatively, you can enable :ref:`Viewport.render_target_v_flip` on the Viewport. Otherwise, the image will appear upside down. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/676 `_ + Properties ---------- diff --git a/classes/class_theme.rst b/classes/class_theme.rst index e01fa83fa..6e5b001ec 100644 --- a/classes/class_theme.rst +++ b/classes/class_theme.rst @@ -35,67 +35,67 @@ Properties Methods ------- -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear` **(** **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_color` **(** :ref:`String` name, :ref:`String` type **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_constant` **(** :ref:`String` name, :ref:`String` type **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_font` **(** :ref:`String` name, :ref:`String` type **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_icon` **(** :ref:`String` name, :ref:`String` type **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear_stylebox` **(** :ref:`String` name, :ref:`String` type **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`copy_default_theme` **(** **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`copy_theme` **(** :ref:`Theme` other **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Color` | :ref:`get_color` **(** :ref:`String` name, :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PoolStringArray` | :ref:`get_color_list` **(** :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_constant` **(** :ref:`String` name, :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PoolStringArray` | :ref:`get_constant_list` **(** :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Font` | :ref:`get_font` **(** :ref:`String` name, :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PoolStringArray` | :ref:`get_font_list` **(** :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Texture` | :ref:`get_icon` **(** :ref:`String` name, :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PoolStringArray` | :ref:`get_icon_list` **(** :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`StyleBox` | :ref:`get_stylebox` **(** :ref:`String` name, :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PoolStringArray` | :ref:`get_stylebox_list` **(** :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PoolStringArray` | :ref:`get_stylebox_types` **(** **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PoolStringArray` | :ref:`get_type_list` **(** :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_color` **(** :ref:`String` name, :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_constant` **(** :ref:`String` name, :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_font` **(** :ref:`String` name, :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_icon` **(** :ref:`String` name, :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has_stylebox` **(** :ref:`String` name, :ref:`String` type **)** |const| | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_color` **(** :ref:`String` name, :ref:`String` type, :ref:`Color` color **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_constant` **(** :ref:`String` name, :ref:`String` type, :ref:`int` constant **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_font` **(** :ref:`String` name, :ref:`String` type, :ref:`Font` font **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_icon` **(** :ref:`String` name, :ref:`String` type, :ref:`Texture` texture **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_stylebox` **(** :ref:`String` name, :ref:`String` type, :ref:`StyleBox` texture **)** | -+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`clear` **(** **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`clear_color` **(** :ref:`String` name, :ref:`String` node_type **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`clear_constant` **(** :ref:`String` name, :ref:`String` node_type **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`clear_font` **(** :ref:`String` name, :ref:`String` node_type **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`clear_icon` **(** :ref:`String` name, :ref:`String` node_type **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`clear_stylebox` **(** :ref:`String` name, :ref:`String` node_type **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`copy_default_theme` **(** **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`copy_theme` **(** :ref:`Theme` other **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Color` | :ref:`get_color` **(** :ref:`String` name, :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PoolStringArray` | :ref:`get_color_list` **(** :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_constant` **(** :ref:`String` name, :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PoolStringArray` | :ref:`get_constant_list` **(** :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Font` | :ref:`get_font` **(** :ref:`String` name, :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PoolStringArray` | :ref:`get_font_list` **(** :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Texture` | :ref:`get_icon` **(** :ref:`String` name, :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PoolStringArray` | :ref:`get_icon_list` **(** :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`StyleBox` | :ref:`get_stylebox` **(** :ref:`String` name, :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PoolStringArray` | :ref:`get_stylebox_list` **(** :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PoolStringArray` | :ref:`get_stylebox_types` **(** **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PoolStringArray` | :ref:`get_type_list` **(** :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`has_color` **(** :ref:`String` name, :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`has_constant` **(** :ref:`String` name, :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`has_font` **(** :ref:`String` name, :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`has_icon` **(** :ref:`String` name, :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`has_stylebox` **(** :ref:`String` name, :ref:`String` node_type **)** |const| | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_color` **(** :ref:`String` name, :ref:`String` node_type, :ref:`Color` color **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_constant` **(** :ref:`String` name, :ref:`String` node_type, :ref:`int` constant **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_font` **(** :ref:`String` name, :ref:`String` node_type, :ref:`Font` font **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_icon` **(** :ref:`String` name, :ref:`String` node_type, :ref:`Texture` texture **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_stylebox` **(** :ref:`String` name, :ref:`String` node_type, :ref:`StyleBox` texture **)** | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Property Descriptions --------------------- @@ -125,41 +125,41 @@ Clears all values on the theme. .. _class_Theme_method_clear_color: -- void **clear_color** **(** :ref:`String` name, :ref:`String` type **)** +- void **clear_color** **(** :ref:`String` name, :ref:`String` node_type **)** -Clears the :ref:`Color` at ``name`` if the theme has ``type``. +Clears the :ref:`Color` at ``name`` if the theme has ``node_type``. ---- .. _class_Theme_method_clear_constant: -- void **clear_constant** **(** :ref:`String` name, :ref:`String` type **)** +- void **clear_constant** **(** :ref:`String` name, :ref:`String` node_type **)** -Clears the constant at ``name`` if the theme has ``type``. +Clears the constant at ``name`` if the theme has ``node_type``. ---- .. _class_Theme_method_clear_font: -- void **clear_font** **(** :ref:`String` name, :ref:`String` type **)** +- void **clear_font** **(** :ref:`String` name, :ref:`String` node_type **)** -Clears the :ref:`Font` at ``name`` if the theme has ``type``. +Clears the :ref:`Font` at ``name`` if the theme has ``node_type``. ---- .. _class_Theme_method_clear_icon: -- void **clear_icon** **(** :ref:`String` name, :ref:`String` type **)** +- void **clear_icon** **(** :ref:`String` name, :ref:`String` node_type **)** -Clears the icon at ``name`` if the theme has ``type``. +Clears the icon at ``name`` if the theme has ``node_type``. ---- .. _class_Theme_method_clear_stylebox: -- void **clear_stylebox** **(** :ref:`String` name, :ref:`String` type **)** +- void **clear_stylebox** **(** :ref:`String` name, :ref:`String` node_type **)** -Clears :ref:`StyleBox` at ``name`` if the theme has ``type``. +Clears :ref:`StyleBox` at ``name`` if the theme has ``node_type``. ---- @@ -181,81 +181,85 @@ Sets the theme's values to a copy of a given theme. .. _class_Theme_method_get_color: -- :ref:`Color` **get_color** **(** :ref:`String` name, :ref:`String` type **)** |const| +- :ref:`Color` **get_color** **(** :ref:`String` name, :ref:`String` node_type **)** |const| -Returns the :ref:`Color` at ``name`` if the theme has ``type``. +Returns the :ref:`Color` at ``name`` if the theme has ``node_type``. ---- .. _class_Theme_method_get_color_list: -- :ref:`PoolStringArray` **get_color_list** **(** :ref:`String` type **)** |const| +- :ref:`PoolStringArray` **get_color_list** **(** :ref:`String` node_type **)** |const| -Returns all the :ref:`Color`\ s as a :ref:`PoolStringArray` filled with each :ref:`Color`'s name, for use in :ref:`get_color`, if the theme has ``type``. +Returns all the :ref:`Color`\ s as a :ref:`PoolStringArray` filled with each :ref:`Color`'s name, for use in :ref:`get_color`, if the theme has ``node_type``. ---- .. _class_Theme_method_get_constant: -- :ref:`int` **get_constant** **(** :ref:`String` name, :ref:`String` type **)** |const| +- :ref:`int` **get_constant** **(** :ref:`String` name, :ref:`String` node_type **)** |const| -Returns the constant at ``name`` if the theme has ``type``. +Returns the constant at ``name`` if the theme has ``node_type``. ---- .. _class_Theme_method_get_constant_list: -- :ref:`PoolStringArray` **get_constant_list** **(** :ref:`String` type **)** |const| +- :ref:`PoolStringArray` **get_constant_list** **(** :ref:`String` node_type **)** |const| -Returns all the constants as a :ref:`PoolStringArray` filled with each constant's name, for use in :ref:`get_constant`, if the theme has ``type``. +Returns all the constants as a :ref:`PoolStringArray` filled with each constant's name, for use in :ref:`get_constant`, if the theme has ``node_type``. ---- .. _class_Theme_method_get_font: -- :ref:`Font` **get_font** **(** :ref:`String` name, :ref:`String` type **)** |const| +- :ref:`Font` **get_font** **(** :ref:`String` name, :ref:`String` node_type **)** |const| -Returns the :ref:`Font` at ``name`` if the theme has ``type``. +Returns the :ref:`Font` at ``name`` if the theme has ``node_type``. ---- .. _class_Theme_method_get_font_list: -- :ref:`PoolStringArray` **get_font_list** **(** :ref:`String` type **)** |const| +- :ref:`PoolStringArray` **get_font_list** **(** :ref:`String` node_type **)** |const| -Returns all the :ref:`Font`\ s as a :ref:`PoolStringArray` filled with each :ref:`Font`'s name, for use in :ref:`get_font`, if the theme has ``type``. +Returns all the :ref:`Font`\ s as a :ref:`PoolStringArray` filled with each :ref:`Font`'s name, for use in :ref:`get_font`, if the theme has ``node_type``. ---- .. _class_Theme_method_get_icon: -- :ref:`Texture` **get_icon** **(** :ref:`String` name, :ref:`String` type **)** |const| +- :ref:`Texture` **get_icon** **(** :ref:`String` name, :ref:`String` node_type **)** |const| -Returns the icon :ref:`Texture` at ``name`` if the theme has ``type``. +Returns the icon :ref:`Texture` at ``name`` if the theme has ``node_type``. ---- .. _class_Theme_method_get_icon_list: -- :ref:`PoolStringArray` **get_icon_list** **(** :ref:`String` type **)** |const| +- :ref:`PoolStringArray` **get_icon_list** **(** :ref:`String` node_type **)** |const| -Returns all the icons as a :ref:`PoolStringArray` filled with each :ref:`Texture`'s name, for use in :ref:`get_icon`, if the theme has ``type``. +Returns all the icons as a :ref:`PoolStringArray` filled with each :ref:`Texture`'s name, for use in :ref:`get_icon`, if the theme has ``node_type``. ---- .. _class_Theme_method_get_stylebox: -- :ref:`StyleBox` **get_stylebox** **(** :ref:`String` name, :ref:`String` type **)** |const| +- :ref:`StyleBox` **get_stylebox** **(** :ref:`String` name, :ref:`String` node_type **)** |const| -Returns the icon :ref:`StyleBox` at ``name`` if the theme has ``type``. +Returns the :ref:`StyleBox` at ``name`` if the theme has ``node_type``. + +Valid ``name``\ s may be found using :ref:`get_stylebox_list`. Valid ``node_type``\ s may be found using :ref:`get_stylebox_types`. ---- .. _class_Theme_method_get_stylebox_list: -- :ref:`PoolStringArray` **get_stylebox_list** **(** :ref:`String` type **)** |const| +- :ref:`PoolStringArray` **get_stylebox_list** **(** :ref:`String` node_type **)** |const| -Returns all the :ref:`StyleBox`\ s as a :ref:`PoolStringArray` filled with each :ref:`StyleBox`'s name, for use in :ref:`get_stylebox`, if the theme has ``type``. +Returns all the :ref:`StyleBox`\ s as a :ref:`PoolStringArray` filled with each :ref:`StyleBox`'s name, for use in :ref:`get_stylebox`, if the theme has ``node_type``. + +Valid ``node_type``\ s may be found using :ref:`get_stylebox_types`. ---- @@ -263,115 +267,115 @@ Returns all the :ref:`StyleBox`\ s as a :ref:`PoolStringArray` **get_stylebox_types** **(** **)** |const| -Returns all the :ref:`StyleBox` types as a :ref:`PoolStringArray` filled with each :ref:`StyleBox`'s type, for use in :ref:`get_stylebox` and/or :ref:`get_stylebox_list`, if the theme has ``type``. +Returns all the :ref:`StyleBox` types as a :ref:`PoolStringArray` filled with each :ref:`StyleBox`'s type, for use in :ref:`get_stylebox` and/or :ref:`get_stylebox_list`, if the theme has ``node_type``. ---- .. _class_Theme_method_get_type_list: -- :ref:`PoolStringArray` **get_type_list** **(** :ref:`String` type **)** |const| +- :ref:`PoolStringArray` **get_type_list** **(** :ref:`String` node_type **)** |const| -Returns all the types in ``type`` as a :ref:`PoolStringArray` for use in any of the ``get_*`` functions, if the theme has ``type``. +Returns all the types in ``node_type`` as a :ref:`PoolStringArray` for use in any of the ``get_*`` functions, if the theme has ``node_type``. ---- .. _class_Theme_method_has_color: -- :ref:`bool` **has_color** **(** :ref:`String` name, :ref:`String` type **)** |const| +- :ref:`bool` **has_color** **(** :ref:`String` name, :ref:`String` node_type **)** |const| -Returns ``true`` if :ref:`Color` with ``name`` is in ``type``. +Returns ``true`` if :ref:`Color` with ``name`` is in ``node_type``. -Returns ``false`` if the theme does not have ``type``. +Returns ``false`` if the theme does not have ``node_type``. ---- .. _class_Theme_method_has_constant: -- :ref:`bool` **has_constant** **(** :ref:`String` name, :ref:`String` type **)** |const| +- :ref:`bool` **has_constant** **(** :ref:`String` name, :ref:`String` node_type **)** |const| -Returns ``true`` if constant with ``name`` is in ``type``. +Returns ``true`` if constant with ``name`` is in ``node_type``. -Returns ``false`` if the theme does not have ``type``. +Returns ``false`` if the theme does not have ``node_type``. ---- .. _class_Theme_method_has_font: -- :ref:`bool` **has_font** **(** :ref:`String` name, :ref:`String` type **)** |const| +- :ref:`bool` **has_font** **(** :ref:`String` name, :ref:`String` node_type **)** |const| -Returns ``true`` if :ref:`Font` with ``name`` is in ``type``. +Returns ``true`` if :ref:`Font` with ``name`` is in ``node_type``. -Returns ``false`` if the theme does not have ``type``. +Returns ``false`` if the theme does not have ``node_type``. ---- .. _class_Theme_method_has_icon: -- :ref:`bool` **has_icon** **(** :ref:`String` name, :ref:`String` type **)** |const| +- :ref:`bool` **has_icon** **(** :ref:`String` name, :ref:`String` node_type **)** |const| -Returns ``true`` if icon :ref:`Texture` with ``name`` is in ``type``. +Returns ``true`` if icon :ref:`Texture` with ``name`` is in ``node_type``. -Returns ``false`` if the theme does not have ``type``. +Returns ``false`` if the theme does not have ``node_type``. ---- .. _class_Theme_method_has_stylebox: -- :ref:`bool` **has_stylebox** **(** :ref:`String` name, :ref:`String` type **)** |const| +- :ref:`bool` **has_stylebox** **(** :ref:`String` name, :ref:`String` node_type **)** |const| -Returns ``true`` if :ref:`StyleBox` with ``name`` is in ``type``. +Returns ``true`` if :ref:`StyleBox` with ``name`` is in ``node_type``. -Returns ``false`` if the theme does not have ``type``. +Returns ``false`` if the theme does not have ``node_type``. ---- .. _class_Theme_method_set_color: -- void **set_color** **(** :ref:`String` name, :ref:`String` type, :ref:`Color` color **)** +- void **set_color** **(** :ref:`String` name, :ref:`String` node_type, :ref:`Color` color **)** -Sets the theme's :ref:`Color` to ``color`` at ``name`` in ``type``. +Sets the theme's :ref:`Color` to ``color`` at ``name`` in ``node_type``. -Does nothing if the theme does not have ``type``. +Does nothing if the theme does not have ``node_type``. ---- .. _class_Theme_method_set_constant: -- void **set_constant** **(** :ref:`String` name, :ref:`String` type, :ref:`int` constant **)** +- void **set_constant** **(** :ref:`String` name, :ref:`String` node_type, :ref:`int` constant **)** -Sets the theme's constant to ``constant`` at ``name`` in ``type``. +Sets the theme's constant to ``constant`` at ``name`` in ``node_type``. -Does nothing if the theme does not have ``type``. +Does nothing if the theme does not have ``node_type``. ---- .. _class_Theme_method_set_font: -- void **set_font** **(** :ref:`String` name, :ref:`String` type, :ref:`Font` font **)** +- void **set_font** **(** :ref:`String` name, :ref:`String` node_type, :ref:`Font` font **)** -Sets the theme's :ref:`Font` to ``font`` at ``name`` in ``type``. +Sets the theme's :ref:`Font` to ``font`` at ``name`` in ``node_type``. -Does nothing if the theme does not have ``type``. +Does nothing if the theme does not have ``node_type``. ---- .. _class_Theme_method_set_icon: -- void **set_icon** **(** :ref:`String` name, :ref:`String` type, :ref:`Texture` texture **)** +- void **set_icon** **(** :ref:`String` name, :ref:`String` node_type, :ref:`Texture` texture **)** -Sets the theme's icon :ref:`Texture` to ``texture`` at ``name`` in ``type``. +Sets the theme's icon :ref:`Texture` to ``texture`` at ``name`` in ``node_type``. -Does nothing if the theme does not have ``type``. +Does nothing if the theme does not have ``node_type``. ---- .. _class_Theme_method_set_stylebox: -- void **set_stylebox** **(** :ref:`String` name, :ref:`String` type, :ref:`StyleBox` texture **)** +- void **set_stylebox** **(** :ref:`String` name, :ref:`String` node_type, :ref:`StyleBox` texture **)** -Sets theme's :ref:`StyleBox` to ``stylebox`` at ``name`` in ``type``. +Sets theme's :ref:`StyleBox` to ``stylebox`` at ``name`` in ``node_type``. -Does nothing if the theme does not have ``type``. +Does nothing if the theme does not have ``node_type``. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_thread.rst b/classes/class_thread.rst index d796fdab7..901fc3022 100644 --- a/classes/class_thread.rst +++ b/classes/class_thread.rst @@ -27,6 +27,8 @@ Tutorials - :doc:`../tutorials/threads/thread_safe_apis` +- `https://godotengine.org/asset-library/asset/676 `_ + Methods ------- diff --git a/classes/class_tilemap.rst b/classes/class_tilemap.rst index f8c356ca3..28a0077b8 100644 --- a/classes/class_tilemap.rst +++ b/classes/class_tilemap.rst @@ -18,11 +18,25 @@ Description Node for 2D tile-based maps. Tilemaps use a :ref:`TileSet` which contain a list of tiles (textures plus optional collision, navigation, and/or occluder shapes) which are used to create grid-based maps. +When doing physics queries against the tilemap, the cell coordinates are encoded as ``metadata`` for each detected collision shape returned by methods such as :ref:`Physics2DDirectSpaceState.intersect_shape`, :ref:`Physics2DDirectBodyState.get_contact_collider_shape_metadata`, etc. + Tutorials --------- - :doc:`../tutorials/2d/using_tilemaps` +- `https://godotengine.org/asset-library/asset/120 `_ + +- `https://godotengine.org/asset-library/asset/112 `_ + +- `https://godotengine.org/asset-library/asset/111 `_ + +- `https://godotengine.org/asset-library/asset/519 `_ + +- `https://godotengine.org/asset-library/asset/520 `_ + +- `https://godotengine.org/asset-library/asset/113 `_ + Properties ---------- @@ -61,6 +75,8 @@ Properties +--------------------------------------------+--------------------------------------------------------------------------------+---------------------------------------+ | :ref:`int` | :ref:`occluder_light_mask` | ``1`` | +--------------------------------------------+--------------------------------------------------------------------------------+---------------------------------------+ +| :ref:`bool` | :ref:`show_collision` | ``false`` | ++--------------------------------------------+--------------------------------------------------------------------------------+---------------------------------------+ | :ref:`TileSet` | :ref:`tile_set` | | +--------------------------------------------+--------------------------------------------------------------------------------+---------------------------------------+ @@ -303,7 +319,7 @@ Position for tile origin. See :ref:`TileOrigin` for pos | *Getter* | is_y_sort_mode_enabled() | +-----------+--------------------------+ -If ``true``, the TileMap's children will be drawn in order of their Y coordinate. +If ``true``, the TileMap's direct children will be drawn in order of their Y coordinate. ---- @@ -369,7 +385,7 @@ Friction value for static body collisions (see ``collision_use_kinematic``). | *Getter* | get_collision_layer() | +-----------+----------------------------+ -The collision layer(s) for all colliders in the TileMap. See `Collision layers and masks `_ in the documentation for more information. +The collision layer(s) for all colliders in the TileMap. See `Collision layers and masks `_ in the documentation for more information. ---- @@ -385,7 +401,7 @@ The collision layer(s) for all colliders in the TileMap. See `Collision layers a | *Getter* | get_collision_mask() | +-----------+---------------------------+ -The collision mask(s) for all colliders in the TileMap. See `Collision layers and masks `_ in the documentation for more information. +The collision mask(s) for all colliders in the TileMap. See `Collision layers and masks `_ in the documentation for more information. ---- @@ -473,6 +489,22 @@ The light mask assigned to all light occluders in the TileMap. The TileSet's lig ---- +.. _class_TileMap_property_show_collision: + +- :ref:`bool` **show_collision** + ++-----------+-----------------------------+ +| *Default* | ``false`` | ++-----------+-----------------------------+ +| *Setter* | set_show_collision(value) | ++-----------+-----------------------------+ +| *Getter* | is_show_collision_enabled() | ++-----------+-----------------------------+ + +If ``true``, collision shapes are shown in the editor and at run-time. Requires **Visible Collision Shapes** to be enabled in the **Debug** menu for collision shapes to be visible at run-time. + +---- + .. _class_TileMap_property_tile_set: - :ref:`TileSet` **tile_set** @@ -596,7 +628,14 @@ Returns ``true`` if the given cell is flipped in the Y axis. - :ref:`Vector2` **map_to_world** **(** :ref:`Vector2` map_position, :ref:`bool` ignore_half_ofs=false **)** |const| -Returns the global position corresponding to the given tilemap (grid-based) coordinates. +Returns the local position of the top left corner of the cell corresponding to the given tilemap (grid-based) coordinates. + +To get the global position, use :ref:`Node2D.to_global`: + +:: + + var local_position = my_tilemap.map_to_world(map_position) + var global_position = my_tilemap.to_global(local_position) Optionally, the tilemap's half offset can be ignored. @@ -620,7 +659,7 @@ Overriding this method also overrides it internally, allowing custom logic to be :: - func set_cell(x, y, tile, flip_x=false, flip_y=false, transpose=false, autotile_coord=Vector2()) + func set_cell(x, y, tile, flip_x=false, flip_y=false, transpose=false, autotile_coord=Vector2()): # Write your custom logic here. # To call the default method: .set_cell(x, y, tile, flip_x, flip_y, transpose, autotile_coord) @@ -691,6 +730,13 @@ Updates the tile map's quadrants, allowing things such as navigation and collisi Returns the tilemap (grid-based) coordinates corresponding to the given local position. +To use this with a global position, first determine the local position with :ref:`Node2D.to_local`: + +:: + + var local_position = my_tilemap.to_local(global_position) + var map_position = my_tilemap.world_to_map(local_position) + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_tileset.rst b/classes/class_tileset.rst index a9f691737..04bcb3bf0 100644 --- a/classes/class_tileset.rst +++ b/classes/class_tileset.rst @@ -20,6 +20,23 @@ A TileSet is a library of tiles for a :ref:`TileMap`. It contains Tiles are referenced by a unique integer ID. +Tutorials +--------- + +- :doc:`../tutorials/2d/using_tilemaps` + +- `https://godotengine.org/asset-library/asset/120 `_ + +- `https://godotengine.org/asset-library/asset/112 `_ + +- `https://godotengine.org/asset-library/asset/111 `_ + +- `https://godotengine.org/asset-library/asset/519 `_ + +- `https://godotengine.org/asset-library/asset/520 `_ + +- `https://godotengine.org/asset-library/asset/113 `_ + Methods ------- diff --git a/classes/class_timer.rst b/classes/class_timer.rst index 063b7624a..199347446 100644 --- a/classes/class_timer.rst +++ b/classes/class_timer.rst @@ -18,7 +18,12 @@ Description Counts down a specified interval and emits a signal on reaching 0. Can be set to repeat or "one-shot" mode. -**Note:** To create an one-shot timer without instantiating a node, use :ref:`SceneTree.create_timer`. +**Note:** To create a one-shot timer without instantiating a node, use :ref:`SceneTree.create_timer`. + +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/515 `_ Properties ---------- diff --git a/classes/class_touchscreenbutton.rst b/classes/class_touchscreenbutton.rst index 89047f012..0c68cc41b 100644 --- a/classes/class_touchscreenbutton.rst +++ b/classes/class_touchscreenbutton.rst @@ -16,7 +16,7 @@ Button for touch screen devices for gameplay use. Description ----------- -TouchScreenButton allows you to create on-screen buttons for touch devices. It's intended for gameplay use, such as a unit you have to touch to move. +TouchScreenButton allows you to create on-screen buttons for touch devices. It's intended for gameplay use, such as a unit you have to touch to move. Unlike :ref:`Button`, TouchScreenButton supports multitouch out of the box. Several TouchScreenButtons can be pressed at the same time with touch input. This node inherits from :ref:`Node2D`. Unlike with :ref:`Control` nodes, you cannot set anchors on it. If you want to create menus or user interfaces, you may want to use :ref:`Button` nodes instead. To make button nodes react to touch events, you can enable the Emulate Mouse option in the Project Settings. @@ -143,7 +143,9 @@ The button's texture for the normal state. | *Getter* | is_passby_press_enabled() | +-----------+---------------------------+ -If ``true``, pass-by presses are enabled. +If ``true``, the :ref:`pressed` and :ref:`released` signals are emitted whenever a pressed finger goes in and out of the button, even if the pressure started outside the active area of the button. + +**Note:** this is a "pass-by" (not "bypass") press mode. ---- diff --git a/classes/class_transform.rst b/classes/class_transform.rst index 70067e143..6228a6448 100644 --- a/classes/class_transform.rst +++ b/classes/class_transform.rst @@ -27,6 +27,12 @@ Tutorials - :doc:`../tutorials/3d/using_transforms` +- `https://godotengine.org/asset-library/asset/584 `_ + +- `https://godotengine.org/asset-library/asset/125 `_ + +- `https://godotengine.org/asset-library/asset/583 `_ + Properties ---------- diff --git a/classes/class_transform2d.rst b/classes/class_transform2d.rst index 47c0e49c8..36b72e2b8 100644 --- a/classes/class_transform2d.rst +++ b/classes/class_transform2d.rst @@ -21,8 +21,14 @@ For more information, read the "Matrices and transforms" documentation article. Tutorials --------- +- :doc:`../tutorials/math/index` + - :doc:`../tutorials/math/matrices_and_transforms` +- `https://godotengine.org/asset-library/asset/584 `_ + +- `https://godotengine.org/asset-library/asset/583 `_ + Properties ---------- diff --git a/classes/class_tree.rst b/classes/class_tree.rst index d88d04db0..9230c9562 100644 --- a/classes/class_tree.rst +++ b/classes/class_tree.rst @@ -66,6 +66,8 @@ Methods +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`TreeItem` | :ref:`create_item` **(** :ref:`Object` parent=null, :ref:`int` idx=-1 **)** | +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`edit_selected` **(** **)** | ++---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`ensure_cursor_is_visible` **(** **)** | +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_column_at_position` **(** :ref:`Vector2` position **)** |const| | @@ -98,6 +100,8 @@ Methods +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_selected_column` **(** **)** |const| | +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`scroll_to_item` **(** :ref:`Object` item **)** | ++---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_column_expand` **(** :ref:`int` column, :ref:`bool` expand **)** | +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_column_min_width` **(** :ref:`int` column, :ref:`int` min_width **)** | @@ -508,6 +512,14 @@ The new item will be the ``idx``\ th child of parent, or it will be the last chi ---- +.. _class_Tree_method_edit_selected: + +- :ref:`bool` **edit_selected** **(** **)** + +Edits the selected tree item as if it was clicked. The item must be set editable with :ref:`TreeItem.set_editable`. Returns ``true`` if the item could be edited. Fails if no item is selected. + +---- + .. _class_Tree_method_ensure_cursor_is_visible: - void **ensure_cursor_is_visible** **(** **)** @@ -568,7 +580,15 @@ To get the item which the returned drop section is relative to, use :ref:`get_it - :ref:`TreeItem` **get_edited** **(** **)** |const| -Returns the currently edited item. This is only available for custom cell mode. +Returns the currently edited item. Can be used with :ref:`item_edited` to get the item that was modified. + +:: + + func _ready(): + $Tree.item_edited.connect(on_Tree_item_edited) + + func on_Tree_item_edited(): + print($Tree.get_edited()) # This item just got edited (e.g. checked). ---- @@ -576,7 +596,7 @@ Returns the currently edited item. This is only available for custom cell mode. - :ref:`int` **get_edited_column** **(** **)** |const| -Returns the column for the currently edited item. This is only available for custom cell mode. +Returns the column for the currently edited item. ---- @@ -654,6 +674,12 @@ To tell whether a column of an item is selected, use :ref:`TreeItem.is_selected< ---- +.. _class_Tree_method_scroll_to_item: + +- void **scroll_to_item** **(** :ref:`Object` item **)** + +---- + .. _class_Tree_method_set_column_expand: - void **set_column_expand** **(** :ref:`int` column, :ref:`bool` expand **)** diff --git a/classes/class_treeitem.rst b/classes/class_treeitem.rst index e1887ea75..3193b05cd 100644 --- a/classes/class_treeitem.rst +++ b/classes/class_treeitem.rst @@ -179,7 +179,7 @@ enum **TreeCellMode**: - **CELL_MODE_STRING** = **0** --- Cell contains a string. -- **CELL_MODE_CHECK** = **1** --- Cell can be checked. +- **CELL_MODE_CHECK** = **1** --- Cell contains a checkbox. - **CELL_MODE_RANGE** = **2** --- Cell contains a range. @@ -399,6 +399,8 @@ Returns the icon :ref:`Texture` region as :ref:`Rect2` **get_metadata** **(** :ref:`int` column **)** |const| +Returns the metadata value that was set for the given column using :ref:`set_metadata`. + ---- .. _class_TreeItem_method_get_next: @@ -449,18 +451,24 @@ If ``wrap`` is enabled, the method will wrap around to the last visible element - :ref:`float` **get_range** **(** :ref:`int` column **)** |const| +Returns the value of a :ref:`CELL_MODE_RANGE` column. + ---- .. _class_TreeItem_method_get_range_config: - :ref:`Dictionary` **get_range_config** **(** :ref:`int` column **)** +Returns a dictionary containing the range parameters for a given column. The keys are "min", "max", "step", and "expr". + ---- .. _class_TreeItem_method_get_suffix: - :ref:`String` **get_suffix** **(** :ref:`int` column **)** |const| +Gets the suffix string shown after the column value. + ---- .. _class_TreeItem_method_get_text: @@ -681,18 +689,26 @@ Sets the given column's icon's texture region. - void **set_metadata** **(** :ref:`int` column, :ref:`Variant` meta **)** +Sets the metadata value for the given column, which can be retrieved later using :ref:`get_metadata`. This can be used, for example, to store a reference to the original data. + ---- .. _class_TreeItem_method_set_range: - void **set_range** **(** :ref:`int` column, :ref:`float` value **)** +Sets the value of a :ref:`CELL_MODE_RANGE` column. + ---- .. _class_TreeItem_method_set_range_config: - void **set_range_config** **(** :ref:`int` column, :ref:`float` min, :ref:`float` max, :ref:`float` step, :ref:`bool` expr=false **)** +Sets the range of accepted values for a column. The column must be in the :ref:`CELL_MODE_RANGE` mode. + +If ``expr`` is ``true``, the edit mode slider will use an exponential scale as with :ref:`Range.exp_edit`. + ---- .. _class_TreeItem_method_set_selectable: @@ -707,12 +723,16 @@ If ``true``, the given column is selectable. - void **set_suffix** **(** :ref:`int` column, :ref:`String` text **)** +Sets a string to be shown after a column's value (for example, a unit abbreviation). + ---- .. _class_TreeItem_method_set_text: - void **set_text** **(** :ref:`int` column, :ref:`String` text **)** +Sets the given column's text value. + ---- .. _class_TreeItem_method_set_text_align: diff --git a/classes/class_tween.rst b/classes/class_tween.rst index 1d183276e..8c3b13428 100644 --- a/classes/class_tween.rst +++ b/classes/class_tween.rst @@ -30,7 +30,7 @@ Here is a brief usage example that makes a 2D node move smoothly between two pos Tween.TRANS_LINEAR, Tween.EASE_IN_OUT) tween.start() -Many methods require a property name, such as ``"position"`` above. You can find the correct property name by hovering over the property in the Inspector. You can also provide the components of a property directly by using ``"property:component"`` (eg. ``position:x``), where it would only apply to that particular component. +Many methods require a property name, such as ``"position"`` above. You can find the correct property name by hovering over the property in the Inspector. You can also provide the components of a property directly by using ``"property:component"`` (e.g. ``position:x``), where it would only apply to that particular component. Many of the methods accept ``trans_type`` and ``ease_type``. The first accepts an :ref:`TransitionType` constant, and refers to the way the timing of the animation is handled (see `easings.net `_ for some examples). The second accepts an :ref:`EaseType` constant, and controls where the ``trans_type`` is applied to the interpolation (in the beginning, the end, or both). If you don't know which transition and easing to pick, you can try different :ref:`TransitionType` constants with :ref:`EASE_IN_OUT`, and use the one that looks best. diff --git a/classes/class_vboxcontainer.rst b/classes/class_vboxcontainer.rst index 05256a822..dcd9497b4 100644 --- a/classes/class_vboxcontainer.rst +++ b/classes/class_vboxcontainer.rst @@ -20,6 +20,11 @@ Description Vertical box container. See :ref:`BoxContainer`. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/676 `_ + Theme Properties ---------------- diff --git a/classes/class_vector2.rst b/classes/class_vector2.rst index 10395902b..0f960049c 100644 --- a/classes/class_vector2.rst +++ b/classes/class_vector2.rst @@ -23,6 +23,16 @@ Tutorials - :doc:`../tutorials/math/index` +- :doc:`../tutorials/math/vector_math` + +- :doc:`../tutorials/math/vectors_advanced` + +- `https://www.youtube.com/playlist?list=PLZHQObOWTQDPD3MizzM2xVFitgF8hE_ab `_ + +- `https://godotengine.org/asset-library/asset/584 `_ + +- `https://github.com/godotengine/godot-demo-projects/tree/master/2d `_ + Properties ---------- @@ -268,7 +278,7 @@ Cubically interpolates between this vector and ``b`` using ``pre_a`` and ``post_ - :ref:`Vector2` **direction_to** **(** :ref:`Vector2` b **)** -Returns the normalized vector pointing from this vector to ``b``. +Returns the normalized vector pointing from this vector to ``b``. This is equivalent to using ``(b - a).normalized()``. ---- @@ -324,7 +334,7 @@ Returns ``true`` if this vector and ``v`` are approximately equal, by running :r - :ref:`bool` **is_normalized** **(** **)** -Returns ``true`` if the vector is normalized, and false otherwise. +Returns ``true`` if the vector is normalized, ``false`` otherwise. ---- @@ -422,7 +432,7 @@ Returns the vector with all components rounded to the nearest integer, with half - :ref:`Vector2` **sign** **(** **)** -Returns the vector with each component set to one or negative one, depending on the signs of the components, or zero if the component is zero, by calling :ref:`@GDScript.sign` on each component. +Returns the vector with each component set to one or negative one, depending on the signs of the components. If a component is zero, it returns positive one. ---- diff --git a/classes/class_vector3.rst b/classes/class_vector3.rst index 89b1f4709..641b36af1 100644 --- a/classes/class_vector3.rst +++ b/classes/class_vector3.rst @@ -23,6 +23,16 @@ Tutorials - :doc:`../tutorials/math/index` +- :doc:`../tutorials/math/vector_math` + +- :doc:`../tutorials/math/vectors_advanced` + +- `https://www.youtube.com/playlist?list=PLZHQObOWTQDPD3MizzM2xVFitgF8hE_ab `_ + +- `https://godotengine.org/asset-library/asset/584 `_ + +- `https://github.com/godotengine/godot-demo-projects/tree/master/3d `_ + Properties ---------- @@ -258,7 +268,7 @@ Performs a cubic interpolation between vectors ``pre_a``, ``a``, ``b``, ``post_b - :ref:`Vector3` **direction_to** **(** :ref:`Vector3` b **)** -Returns the normalized vector pointing from this vector to ``b``. +Returns the normalized vector pointing from this vector to ``b``. This is equivalent to using ``(b - a).normalized()``. ---- @@ -322,7 +332,7 @@ Returns ``true`` if this vector and ``v`` are approximately equal, by running :r - :ref:`bool` **is_normalized** **(** **)** -Returns ``true`` if the vector is normalized, and false otherwise. +Returns ``true`` if the vector is normalized, ``false`` otherwise. ---- @@ -444,7 +454,7 @@ Returns this vector with all components rounded to the nearest integer, with hal - :ref:`Vector3` **sign** **(** **)** -Returns a vector with each component set to one or negative one, depending on the signs of this vector's components, or zero if the component is zero, by calling :ref:`@GDScript.sign` on each component. +Returns a vector with each component set to one or negative one, depending on the signs of this vector's components. If a component is zero, it returns positive one. ---- diff --git a/classes/class_vehiclebody.rst b/classes/class_vehiclebody.rst index b66776582..01a7d6556 100644 --- a/classes/class_vehiclebody.rst +++ b/classes/class_vehiclebody.rst @@ -22,6 +22,11 @@ This node implements all the physics logic needed to simulate a car. It is based **Note:** This class has known issues and isn't designed to provide realistic 3D vehicle physics. If you want advanced vehicle physics, you will probably have to write your own physics integration using another :ref:`PhysicsBody` class. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/524 `_ + Properties ---------- diff --git a/classes/class_vehiclewheel.rst b/classes/class_vehiclewheel.rst index 6a959b1ed..9adad966a 100644 --- a/classes/class_vehiclewheel.rst +++ b/classes/class_vehiclewheel.rst @@ -20,6 +20,11 @@ This node needs to be used as a child node of :ref:`VehicleBody` class. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/524 `_ + Properties ---------- diff --git a/classes/class_videoplayer.rst b/classes/class_videoplayer.rst index d621245df..1b66d450f 100644 --- a/classes/class_videoplayer.rst +++ b/classes/class_videoplayer.rst @@ -18,7 +18,11 @@ Description Control node for playing video streams using :ref:`VideoStream` resources. -Supported video formats are `WebM `_ (:ref:`VideoStreamWebm`), `Ogg Theora `_ (:ref:`VideoStreamTheora`), and any format exposed via a GDNative plugin using :ref:`VideoStreamGDNative`. +Supported video formats are `WebM `_ (``.webm``, :ref:`VideoStreamWebm`), `Ogg Theora `_ (``.ogv``, :ref:`VideoStreamTheora`), and any format exposed via a GDNative plugin using :ref:`VideoStreamGDNative`. + +**Note:** Due to a bug, VideoPlayer does not support localization remapping yet. + +**Warning:** On HTML5, video playback *will* perform poorly due to missing architecture-specific assembly optimizations, especially for VP8/VP9. Properties ---------- diff --git a/classes/class_videostreamtheora.rst b/classes/class_videostreamtheora.rst index 1531b5b4a..d54cfd9e9 100644 --- a/classes/class_videostreamtheora.rst +++ b/classes/class_videostreamtheora.rst @@ -16,7 +16,9 @@ VideoStreamTheora Description ----------- -:ref:`VideoStream` resource handling the `Ogg Theora `_ video format with ``.ogv`` extension. +:ref:`VideoStream` resource handling the `Ogg Theora `_ video format with ``.ogv`` extension. The Theora codec is less efficient than :ref:`VideoStreamWebm`'s VP8 and VP9, but it requires less CPU resources to decode. The Theora codec is decoded on the CPU. + +**Note:** While Ogg Theora videos can also have an ``.ogg`` extension, you will have to rename the extension to ``.ogv`` to use those videos within Godot. Methods ------- @@ -42,7 +44,7 @@ Returns the Ogg Theora video file handled by this ``VideoStreamTheora``. - void **set_file** **(** :ref:`String` file **)** -Sets the Ogg Theora video file that this ``VideoStreamTheora`` resource handles. The ``file`` name should have the ``.o`` extension. +Sets the Ogg Theora video file that this ``VideoStreamTheora`` resource handles. The ``file`` name should have the ``.ogv`` extension. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_videostreamwebm.rst b/classes/class_videostreamwebm.rst index 12d7966b4..742f0c085 100644 --- a/classes/class_videostreamwebm.rst +++ b/classes/class_videostreamwebm.rst @@ -16,7 +16,11 @@ VideoStreamWebm Description ----------- -:ref:`VideoStream` resource handling the `WebM `_ video format with ``.webm`` extension. +:ref:`VideoStream` resource handling the `WebM `_ video format with ``.webm`` extension. Both the VP8 and VP9 codecs are supported. The VP8 and VP9 codecs are more efficient than :ref:`VideoStreamTheora`, but they require more CPU resources to decode (especially VP9). Both the VP8 and VP9 codecs are decoded on the CPU. + +**Note:** Alpha channel (also known as transparency) is not supported. The video will always appear to have a black background, even if it originally contains an alpha channel. + +**Note:** There are known bugs and performance issues with WebM video playback in Godot. If you run into problems, try using the Ogg Theora format instead: :ref:`VideoStreamTheora` Methods ------- diff --git a/classes/class_viewport.rst b/classes/class_viewport.rst index c1d8ebccb..079e36ebe 100644 --- a/classes/class_viewport.rst +++ b/classes/class_viewport.rst @@ -35,6 +35,18 @@ Tutorials - :doc:`../tutorials/viewports/index` +- `https://godotengine.org/asset-library/asset/127 `_ + +- `https://godotengine.org/asset-library/asset/128 `_ + +- `https://godotengine.org/asset-library/asset/129 `_ + +- `https://godotengine.org/asset-library/asset/130 `_ + +- `https://godotengine.org/asset-library/asset/541 `_ + +- `https://godotengine.org/asset-library/asset/586 `_ + Properties ---------- @@ -47,10 +59,14 @@ Properties +---------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+---------------------+ | :ref:`Transform2D` | :ref:`canvas_transform` | | +---------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+---------------------+ +| :ref:`bool` | :ref:`debanding` | ``false`` | ++---------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+---------------------+ | :ref:`DebugDraw` | :ref:`debug_draw` | ``0`` | +---------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+---------------------+ | :ref:`bool` | :ref:`disable_3d` | ``false`` | +---------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+---------------------+ +| :ref:`bool` | :ref:`fxaa` | ``false`` | ++---------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+---------------------+ | :ref:`Transform2D` | :ref:`global_canvas_transform` | | +---------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+---------------------+ | :ref:`bool` | :ref:`gui_disable_input` | ``false`` | @@ -428,6 +444,24 @@ The canvas transform of the viewport, useful for changing the on-screen position ---- +.. _class_Viewport_property_debanding: + +- :ref:`bool` **debanding** + ++-----------+--------------------------+ +| *Default* | ``false`` | ++-----------+--------------------------+ +| *Setter* | set_use_debanding(value) | ++-----------+--------------------------+ +| *Getter* | get_use_debanding() | ++-----------+--------------------------+ + +If ``true``, uses a fast post-processing filter to make banding significantly less visible. In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger. + +**Note:** Only available on the GLES3 backend. :ref:`hdr` must also be ``true`` for debanding to be effective. + +---- + .. _class_Viewport_property_debug_draw: - :ref:`DebugDraw` **debug_draw** @@ -460,6 +494,22 @@ If ``true``, the viewport will disable 3D rendering. For actual disabling use `` ---- +.. _class_Viewport_property_fxaa: + +- :ref:`bool` **fxaa** + ++-----------+---------------------+ +| *Default* | ``false`` | ++-----------+---------------------+ +| *Setter* | set_use_fxaa(value) | ++-----------+---------------------+ +| *Getter* | get_use_fxaa() | ++-----------+---------------------+ + +Enables fast approximate antialiasing. FXAA is a popular screen-space antialiasing method, which is fast but will make the image look blurry, especially at lower resolutions. It can still work relatively well at large resolutions such as 1440p and 4K. + +---- + .. _class_Viewport_property_global_canvas_transform: - :ref:`Transform2D` **global_canvas_transform** @@ -486,7 +536,7 @@ The global canvas transform of the viewport. The canvas transform is relative to | *Getter* | is_input_disabled() | +-----------+--------------------------+ -If ``true``, the viewport will not receive input event. +If ``true``, the viewport will not receive input events. ---- diff --git a/classes/class_viewporttexture.rst b/classes/class_viewporttexture.rst index 510893fce..3279cc76a 100644 --- a/classes/class_viewporttexture.rst +++ b/classes/class_viewporttexture.rst @@ -20,6 +20,17 @@ Displays the content of a :ref:`Viewport` node as a dynamic :ref To create a ViewportTexture in code, use the :ref:`Viewport.get_texture` method on the target viewport. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/127 `_ + +- `https://godotengine.org/asset-library/asset/128 `_ + +- `https://godotengine.org/asset-library/asset/129 `_ + +- `https://godotengine.org/asset-library/asset/586 `_ + Properties ---------- diff --git a/classes/class_visibilitynotifier.rst b/classes/class_visibilitynotifier.rst index 05bd1203e..cbc18beaf 100644 --- a/classes/class_visibilitynotifier.rst +++ b/classes/class_visibilitynotifier.rst @@ -22,7 +22,7 @@ The VisibilityNotifier detects when it is visible on the screen. It also notifie If you want nodes to be disabled automatically when they exit the screen, use :ref:`VisibilityEnabler` instead. -**Note:** VisibilityNotifier uses an approximate heuristic for performance reasons. It does't take walls and other occlusion into account. The heuristic is an implementation detail and may change in future versions. If you need precise visibility checking, use another method such as adding an :ref:`Area` node as a child of a :ref:`Camera` node and/or :ref:`Vector3.dot`. +**Note:** VisibilityNotifier uses an approximate heuristic for performance reasons. It doesn't take walls and other occlusion into account. The heuristic is an implementation detail and may change in future versions. If you need precise visibility checking, use another method such as adding an :ref:`Area` node as a child of a :ref:`Camera` node and/or :ref:`Vector3.dot`. Properties ---------- diff --git a/classes/class_visibilitynotifier2d.rst b/classes/class_visibilitynotifier2d.rst index 083d947a0..3212643e2 100644 --- a/classes/class_visibilitynotifier2d.rst +++ b/classes/class_visibilitynotifier2d.rst @@ -24,6 +24,11 @@ If you want nodes to be disabled automatically when they exit the screen, use :r **Note:** For performance reasons, VisibilityNotifier2D uses an approximate heuristic with precision determined by :ref:`ProjectSettings.world/2d/cell_size`. If you need precise visibility checking, use another method such as adding an :ref:`Area2D` node as a child of a :ref:`Camera2D` node. +Tutorials +--------- + +- `https://godotengine.org/asset-library/asset/515 `_ + Properties ---------- diff --git a/classes/class_visualscriptlists.rst b/classes/class_visualscriptlists.rst index 86de05adb..337e73f7b 100644 --- a/classes/class_visualscriptlists.rst +++ b/classes/class_visualscriptlists.rst @@ -18,7 +18,7 @@ A Visual Script virtual class for in-graph editable nodes. Description ----------- -A Visual Script virtual class that defines the shape and the default behaviour of the nodes that have to be in-graph editable nodes. +A Visual Script virtual class that defines the shape and the default behavior of the nodes that have to be in-graph editable nodes. Methods ------- diff --git a/classes/class_visualscriptpropertyget.rst b/classes/class_visualscriptpropertyget.rst index ab912147d..bc53f214f 100644 --- a/classes/class_visualscriptpropertyget.rst +++ b/classes/class_visualscriptpropertyget.rst @@ -43,6 +43,8 @@ Enumerations .. _class_VisualScriptPropertyGet_constant_CALL_MODE_INSTANCE: +.. _class_VisualScriptPropertyGet_constant_CALL_MODE_BASIC_TYPE: + enum **CallMode**: - **CALL_MODE_SELF** = **0** @@ -51,6 +53,8 @@ enum **CallMode**: - **CALL_MODE_INSTANCE** = **2** +- **CALL_MODE_BASIC_TYPE** = **3** + Property Descriptions --------------------- diff --git a/classes/class_visualserver.rst b/classes/class_visualserver.rst index 1f4015f94..db3363f71 100644 --- a/classes/class_visualserver.rst +++ b/classes/class_visualserver.rst @@ -28,7 +28,7 @@ All objects are drawn to a viewport. You can use the :ref:`Viewport` node with :ref:`Spatial.get_world`. Otherwise, a scenario can be created with :ref:`scenario_create`. -Similarly in 2D, a canvas is needed to draw all canvas items. +Similarly, in 2D, a canvas is needed to draw all canvas items. In 3D, all visible objects are comprised of a resource and an instance. A resource can be a mesh, a particle system, a light, or any other 3D object. In order to be visible resources must be attached to an instance using :ref:`instance_set_base`. The instance must also be attached to the scenario using :ref:`instance_set_scenario` in order to be visible. @@ -384,7 +384,7 @@ Methods +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`instance_set_transform` **(** :ref:`RID` instance, :ref:`Transform` transform **)** | +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`instance_set_use_lightmap` **(** :ref:`RID` instance, :ref:`RID` lightmap_instance, :ref:`RID` lightmap **)** | +| void | :ref:`instance_set_use_lightmap` **(** :ref:`RID` instance, :ref:`RID` lightmap_instance, :ref:`RID` lightmap, :ref:`int` lightmap_slice=-1, :ref:`Rect2` lightmap_uv_rect=Rect2( 0, 0, 1, 1 ) **)** | +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`instance_set_visible` **(** :ref:`RID` instance, :ref:`bool` visible **)** | +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -404,6 +404,8 @@ Methods +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`light_omni_set_shadow_mode` **(** :ref:`RID` light, :ref:`LightOmniShadowMode` mode **)** | +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`light_set_bake_mode` **(** :ref:`RID` light, :ref:`LightBakeMode` bake_mode **)** | ++---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`light_set_color` **(** :ref:`RID` light, :ref:`Color` color **)** | +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`light_set_cull_mask` **(** :ref:`RID` light, :ref:`int` mask **)** | @@ -434,10 +436,14 @@ Methods +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform` | :ref:`lightmap_capture_get_octree_cell_transform` **(** :ref:`RID` capture **)** |const| | +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`lightmap_capture_is_interior` **(** :ref:`RID` capture **)** |const| | ++---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`lightmap_capture_set_bounds` **(** :ref:`RID` capture, :ref:`AABB` bounds **)** | +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`lightmap_capture_set_energy` **(** :ref:`RID` capture, :ref:`float` energy **)** | +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`lightmap_capture_set_interior` **(** :ref:`RID` capture, :ref:`bool` interior **)** | ++---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`lightmap_capture_set_octree` **(** :ref:`RID` capture, :ref:`PoolByteArray` octree **)** | +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`lightmap_capture_set_octree_cell_subdiv` **(** :ref:`RID` capture, :ref:`int` subdiv **)** | @@ -780,6 +786,10 @@ Methods +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`viewport_set_use_arvr` **(** :ref:`RID` viewport, :ref:`bool` use_arvr **)** | +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`viewport_set_use_debanding` **(** :ref:`RID` viewport, :ref:`bool` debanding **)** | ++---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`viewport_set_use_fxaa` **(** :ref:`RID` viewport, :ref:`bool` fxaa **)** | ++---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`viewport_set_vflip` **(** :ref:`RID` viewport, :ref:`bool` enabled **)** | +---------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -1189,6 +1199,24 @@ enum **LightParam**: ---- +.. _enum_VisualServer_LightBakeMode: + +.. _class_VisualServer_constant_LIGHT_BAKE_DISABLED: + +.. _class_VisualServer_constant_LIGHT_BAKE_INDIRECT: + +.. _class_VisualServer_constant_LIGHT_BAKE_ALL: + +enum **LightBakeMode**: + +- **LIGHT_BAKE_DISABLED** = **0** + +- **LIGHT_BAKE_INDIRECT** = **1** + +- **LIGHT_BAKE_ALL** = **2** + +---- + .. _enum_VisualServer_LightOmniShadowMode: .. _class_VisualServer_constant_LIGHT_OMNI_SHADOW_DUAL_PARABOLOID: @@ -3052,7 +3080,9 @@ Not yet implemented. Always returns ``false``. - :ref:`bool` **has_os_feature** **(** :ref:`String` feature **)** |const| -Returns ``true`` if the OS supports a certain feature. Features might be ``s3tc``, ``etc``, ``etc2`` and ``pvrtc``. +Returns ``true`` if the OS supports a certain feature. Features might be ``s3tc``, ``etc``, ``etc2``, ``pvrtc`` and ``skinning_fallback``. + +When rendering with GLES2, returns ``true`` with ``skinning_fallback`` in case the hardware doesn't support the default GPU skinning process. ---- @@ -3286,7 +3316,7 @@ Function not implemented in Godot 3.x. - void **instance_set_extra_visibility_margin** **(** :ref:`RID` instance, :ref:`float` margin **)** -Sets a margin to increase the size of the AABB when culling objects from the view frustum. This allows you avoid culling objects that fall outside the view frustum. Equivalent to :ref:`GeometryInstance.extra_cull_margin`. +Sets a margin to increase the size of the AABB when culling objects from the view frustum. This allows you to avoid culling objects that fall outside the view frustum. Equivalent to :ref:`GeometryInstance.extra_cull_margin`. ---- @@ -3324,7 +3354,7 @@ Sets the world space transform of the instance. Equivalent to :ref:`Spatial.tran .. _class_VisualServer_method_instance_set_use_lightmap: -- void **instance_set_use_lightmap** **(** :ref:`RID` instance, :ref:`RID` lightmap_instance, :ref:`RID` lightmap **)** +- void **instance_set_use_lightmap** **(** :ref:`RID` instance, :ref:`RID` lightmap_instance, :ref:`RID` lightmap, :ref:`int` lightmap_slice=-1, :ref:`Rect2` lightmap_uv_rect=Rect2( 0, 0, 1, 1 ) **)** Sets the lightmap to use with this instance. @@ -3408,6 +3438,14 @@ Sets whether to use a dual paraboloid or a cubemap for the shadow map. Dual para ---- +.. _class_VisualServer_method_light_set_bake_mode: + +- void **light_set_bake_mode** **(** :ref:`RID` light, :ref:`LightBakeMode` bake_mode **)** + +Sets the bake mode for this light, see :ref:`LightBakeMode` for options. The bake mode affects how the light will be baked in :ref:`BakedLightmap`\ s and :ref:`GIProbe`\ s. + +---- + .. _class_VisualServer_method_light_set_color: - void **light_set_color** **(** :ref:`RID` light, :ref:`Color` color **)** @@ -3476,7 +3514,7 @@ Sets the color of the shadow cast by the light. Equivalent to :ref:`Light.shadow - void **light_set_use_gi** **(** :ref:`RID` light, :ref:`bool` enabled **)** -Sets whether GI probes capture light information from this light. +Sets whether GI probes capture light information from this light. *Deprecated method.* Use :ref:`light_set_bake_mode` instead. This method is only kept for compatibility reasons and calls :ref:`light_set_bake_mode` internally, setting the bake mode to :ref:`LIGHT_BAKE_DISABLED` or :ref:`LIGHT_BAKE_INDIRECT` depending on the given parameter. ---- @@ -3532,6 +3570,14 @@ Returns the cell transform for this lightmap capture's octree. ---- +.. _class_VisualServer_method_lightmap_capture_is_interior: + +- :ref:`bool` **lightmap_capture_is_interior** **(** :ref:`RID` capture **)** |const| + +Returns ``true`` if capture is in "interior" mode. + +---- + .. _class_VisualServer_method_lightmap_capture_set_bounds: - void **lightmap_capture_set_bounds** **(** :ref:`RID` capture, :ref:`AABB` bounds **)** @@ -3548,6 +3594,14 @@ Sets the energy multiplier for this lightmap capture. Equivalent to :ref:`BakedL ---- +.. _class_VisualServer_method_lightmap_capture_set_interior: + +- void **lightmap_capture_set_interior** **(** :ref:`RID` capture, :ref:`bool` interior **)** + +Sets the "interior" mode for this lightmap capture. Equivalent to :ref:`BakedLightmapData.interior`. + +---- + .. _class_VisualServer_method_lightmap_capture_set_octree: - void **lightmap_capture_set_octree** **(** :ref:`RID` capture, :ref:`PoolByteArray` octree **)** @@ -4178,7 +4232,7 @@ If ``true``, particles will emit once and then stop. Equivalent to :ref:`Particl - void **particles_set_pre_process_time** **(** :ref:`RID` particles, :ref:`float` time **)** -Sets the preprocess time for the particles animation. This lets you delay starting an animation until after the particles have begun emitting. Equivalent to :ref:`Particles.preprocess`. +Sets the preprocess time for the particles' animation. This lets you delay starting an animation until after the particles have begun emitting. Equivalent to :ref:`Particles.preprocess`. ---- @@ -4982,6 +5036,24 @@ If ``true``, the viewport uses augmented or virtual reality technologies. See :r ---- +.. _class_VisualServer_method_viewport_set_use_debanding: + +- void **viewport_set_use_debanding** **(** :ref:`RID` viewport, :ref:`bool` debanding **)** + +If ``true``, uses a fast post-processing filter to make banding significantly less visible. In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger. + +**Note:** Only available on the GLES3 backend. :ref:`Viewport.hdr` must also be ``true`` for debanding to be effective. + +---- + +.. _class_VisualServer_method_viewport_set_use_fxaa: + +- void **viewport_set_use_fxaa** **(** :ref:`RID` viewport, :ref:`bool` fxaa **)** + +Enables fast approximate antialiasing for this viewport. FXAA is a popular screen-space antialiasing method, which is fast but will make the image look blurry, especially at lower resolutions. It can still work relatively well at large resolutions such as 1440p and 4K. + +---- + .. _class_VisualServer_method_viewport_set_vflip: - void **viewport_set_vflip** **(** :ref:`RID` viewport, :ref:`bool` enabled **)** diff --git a/classes/class_visualshadernode.rst b/classes/class_visualshadernode.rst index e29a10851..de44e66e7 100644 --- a/classes/class_visualshadernode.rst +++ b/classes/class_visualshadernode.rst @@ -11,7 +11,7 @@ VisualShaderNode **Inherits:** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` -**Inherited By:** :ref:`VisualShaderNodeBooleanConstant`, :ref:`VisualShaderNodeColorConstant`, :ref:`VisualShaderNodeColorFunc`, :ref:`VisualShaderNodeColorOp`, :ref:`VisualShaderNodeCompare`, :ref:`VisualShaderNodeCubeMap`, :ref:`VisualShaderNodeCustom`, :ref:`VisualShaderNodeDeterminant`, :ref:`VisualShaderNodeDotProduct`, :ref:`VisualShaderNodeFaceForward`, :ref:`VisualShaderNodeFresnel`, :ref:`VisualShaderNodeGroupBase`, :ref:`VisualShaderNodeIf`, :ref:`VisualShaderNodeInput`, :ref:`VisualShaderNodeIs`, :ref:`VisualShaderNodeOuterProduct`, :ref:`VisualShaderNodeOutput`, :ref:`VisualShaderNodeScalarClamp`, :ref:`VisualShaderNodeScalarConstant`, :ref:`VisualShaderNodeScalarDerivativeFunc`, :ref:`VisualShaderNodeScalarFunc`, :ref:`VisualShaderNodeScalarInterp`, :ref:`VisualShaderNodeScalarOp`, :ref:`VisualShaderNodeScalarSmoothStep`, :ref:`VisualShaderNodeSwitch`, :ref:`VisualShaderNodeTexture`, :ref:`VisualShaderNodeTransformCompose`, :ref:`VisualShaderNodeTransformConstant`, :ref:`VisualShaderNodeTransformDecompose`, :ref:`VisualShaderNodeTransformFunc`, :ref:`VisualShaderNodeTransformMult`, :ref:`VisualShaderNodeTransformVecMult`, :ref:`VisualShaderNodeUniform`, :ref:`VisualShaderNodeVec3Constant`, :ref:`VisualShaderNodeVectorClamp`, :ref:`VisualShaderNodeVectorCompose`, :ref:`VisualShaderNodeVectorDecompose`, :ref:`VisualShaderNodeVectorDerivativeFunc`, :ref:`VisualShaderNodeVectorDistance`, :ref:`VisualShaderNodeVectorFunc`, :ref:`VisualShaderNodeVectorInterp`, :ref:`VisualShaderNodeVectorLen`, :ref:`VisualShaderNodeVectorOp`, :ref:`VisualShaderNodeVectorRefract`, :ref:`VisualShaderNodeVectorScalarMix`, :ref:`VisualShaderNodeVectorScalarSmoothStep`, :ref:`VisualShaderNodeVectorScalarStep`, :ref:`VisualShaderNodeVectorSmoothStep` +**Inherited By:** :ref:`VisualShaderNodeBooleanConstant`, :ref:`VisualShaderNodeColorConstant`, :ref:`VisualShaderNodeColorFunc`, :ref:`VisualShaderNodeColorOp`, :ref:`VisualShaderNodeCompare`, :ref:`VisualShaderNodeCubeMap`, :ref:`VisualShaderNodeCustom`, :ref:`VisualShaderNodeDeterminant`, :ref:`VisualShaderNodeDotProduct`, :ref:`VisualShaderNodeFaceForward`, :ref:`VisualShaderNodeFresnel`, :ref:`VisualShaderNodeGroupBase`, :ref:`VisualShaderNodeIf`, :ref:`VisualShaderNodeInput`, :ref:`VisualShaderNodeIs`, :ref:`VisualShaderNodeOuterProduct`, :ref:`VisualShaderNodeOutput`, :ref:`VisualShaderNodeScalarClamp`, :ref:`VisualShaderNodeScalarConstant`, :ref:`VisualShaderNodeScalarDerivativeFunc`, :ref:`VisualShaderNodeScalarFunc`, :ref:`VisualShaderNodeScalarInterp`, :ref:`VisualShaderNodeScalarOp`, :ref:`VisualShaderNodeScalarSmoothStep`, :ref:`VisualShaderNodeSwitch`, :ref:`VisualShaderNodeTexture`, :ref:`VisualShaderNodeTransformCompose`, :ref:`VisualShaderNodeTransformConstant`, :ref:`VisualShaderNodeTransformDecompose`, :ref:`VisualShaderNodeTransformFunc`, :ref:`VisualShaderNodeTransformMult`, :ref:`VisualShaderNodeTransformVecMult`, :ref:`VisualShaderNodeUniform`, :ref:`VisualShaderNodeUniformRef`, :ref:`VisualShaderNodeVec3Constant`, :ref:`VisualShaderNodeVectorClamp`, :ref:`VisualShaderNodeVectorCompose`, :ref:`VisualShaderNodeVectorDecompose`, :ref:`VisualShaderNodeVectorDerivativeFunc`, :ref:`VisualShaderNodeVectorDistance`, :ref:`VisualShaderNodeVectorFunc`, :ref:`VisualShaderNodeVectorInterp`, :ref:`VisualShaderNodeVectorLen`, :ref:`VisualShaderNodeVectorOp`, :ref:`VisualShaderNodeVectorRefract`, :ref:`VisualShaderNodeVectorScalarMix`, :ref:`VisualShaderNodeVectorScalarSmoothStep`, :ref:`VisualShaderNodeVectorScalarStep`, :ref:`VisualShaderNodeVectorSmoothStep` Base class for nodes in a visual shader graph. diff --git a/classes/class_visualshadernodecustom.rst b/classes/class_visualshadernodecustom.rst index 30c974bf2..eb379f81a 100644 --- a/classes/class_visualshadernodecustom.rst +++ b/classes/class_visualshadernodecustom.rst @@ -69,7 +69,7 @@ Method Descriptions - :ref:`String` **_get_category** **(** **)** |virtual| -Override this method to define the category of the associated custom node in the Visual Shader Editor's members dialog. +Override this method to define the category of the associated custom node in the Visual Shader Editor's members dialog. The path may look like ``"MyGame/MyFunctions/Noise"``. Defining this method is **optional**. If not overridden, the node will be filed under the "Custom" category. diff --git a/classes/class_visualshadernodedeterminant.rst b/classes/class_visualshadernodedeterminant.rst index 2f30c5f03..68ae0253f 100644 --- a/classes/class_visualshadernodedeterminant.rst +++ b/classes/class_visualshadernodedeterminant.rst @@ -16,7 +16,7 @@ Calculates the determinant of a :ref:`Transform` within the vis Description ----------- -Translates to ``deteminant(x)`` in the shader language. +Translates to ``determinant(x)`` in the shader language. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_visualshadernodeexpression.rst b/classes/class_visualshadernodeexpression.rst index cccbff374..84af1d86a 100644 --- a/classes/class_visualshadernodeexpression.rst +++ b/classes/class_visualshadernodeexpression.rst @@ -20,7 +20,7 @@ Description Custom Godot Shading Language expression, with a custom amount of input and output ports. -The provided code is directly injected into the graph's matching shader function (``vertex``, ``fragment``, or ``light``), so it cannot be used to to declare functions, varyings, uniforms, or global constants. See :ref:`VisualShaderNodeGlobalExpression` for such global definitions. +The provided code is directly injected into the graph's matching shader function (``vertex``, ``fragment``, or ``light``), so it cannot be used to declare functions, varyings, uniforms, or global constants. See :ref:`VisualShaderNodeGlobalExpression` for such global definitions. Properties ---------- diff --git a/classes/class_visualshadernodefaceforward.rst b/classes/class_visualshadernodefaceforward.rst index 9fdaa900e..fceaa754f 100644 --- a/classes/class_visualshadernodefaceforward.rst +++ b/classes/class_visualshadernodefaceforward.rst @@ -16,7 +16,7 @@ Returns the vector that points in the same direction as a reference vector withi Description ----------- -Translates to ``faceforward(N, I, Nref)`` in the shader language. The function has three vector parameters: ``N``, the vector to orient, ``I``, the incident vector, and ``Nref``, the reference vector. If the dot product of ``I`` and ``Nref`` is smaller than zero the return value is ``N``. Otherwise ``-N`` is returned. +Translates to ``faceforward(N, I, Nref)`` in the shader language. The function has three vector parameters: ``N``, the vector to orient, ``I``, the incident vector, and ``Nref``, the reference vector. If the dot product of ``I`` and ``Nref`` is smaller than zero the return value is ``N``. Otherwise, ``-N`` is returned. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_visualshadernodegroupbase.rst b/classes/class_visualshadernodegroupbase.rst index bec112a37..1b85b1314 100644 --- a/classes/class_visualshadernodegroupbase.rst +++ b/classes/class_visualshadernodegroupbase.rst @@ -154,7 +154,7 @@ Returns the number of input ports in use. Alternative for :ref:`get_free_input_p - :ref:`String` **get_inputs** **(** **)** |const| -Returns a :ref:`String` description of the input ports as as colon-separated list using the format ``id,type,name;`` (see :ref:`add_input_port`). +Returns a :ref:`String` description of the input ports as a colon-separated list using the format ``id,type,name;`` (see :ref:`add_input_port`). ---- @@ -170,7 +170,7 @@ Returns the number of output ports in use. Alternative for :ref:`get_free_output - :ref:`String` **get_outputs** **(** **)** |const| -Returns a :ref:`String` description of the output ports as as colon-separated list using the format ``id,type,name;`` (see :ref:`add_output_port`). +Returns a :ref:`String` description of the output ports as a colon-separated list using the format ``id,type,name;`` (see :ref:`add_output_port`). ---- diff --git a/classes/class_visualshadernodeoutput.rst b/classes/class_visualshadernodeoutput.rst index 10f2d193e..d48cdaeb5 100644 --- a/classes/class_visualshadernodeoutput.rst +++ b/classes/class_visualshadernodeoutput.rst @@ -16,7 +16,7 @@ Represents the output shader parameters within the visual shader graph. Description ----------- -This visual shader node is present in all shader graphs in form of "Output" block with mutliple output value ports. +This visual shader node is present in all shader graphs in form of "Output" block with multiple output value ports. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_visualshadernodeuniformref.rst b/classes/class_visualshadernodeuniformref.rst new file mode 100644 index 000000000..502af4f57 --- /dev/null +++ b/classes/class_visualshadernodeuniformref.rst @@ -0,0 +1,47 @@ +:github_url: hide + +.. Generated automatically by doc/tools/makerst.py in Godot's source tree. +.. DO NOT EDIT THIS FILE, but the VisualShaderNodeUniformRef.xml source instead. +.. The source is found in doc/classes or modules//doc_classes. + +.. _class_VisualShaderNodeUniformRef: + +VisualShaderNodeUniformRef +========================== + +**Inherits:** :ref:`VisualShaderNode` **<** :ref:`Resource` **<** :ref:`Reference` **<** :ref:`Object` + +A reference to an existing :ref:`VisualShaderNodeUniform`. + +Description +----------- + +Creating a reference to a :ref:`VisualShaderNodeUniform` allows you to reuse this uniform in different shaders or shader stages easily. + +Properties +---------- + ++-----------------------------+-----------------------------------------------------------------------------+--------------+ +| :ref:`String` | :ref:`uniform_name` | ``"[None]"`` | ++-----------------------------+-----------------------------------------------------------------------------+--------------+ + +Property Descriptions +--------------------- + +.. _class_VisualShaderNodeUniformRef_property_uniform_name: + +- :ref:`String` **uniform_name** + ++-----------+-------------------------+ +| *Default* | ``"[None]"`` | ++-----------+-------------------------+ +| *Setter* | set_uniform_name(value) | ++-----------+-------------------------+ +| *Getter* | get_uniform_name() | ++-----------+-------------------------+ + +The name of the uniform which this reference points to. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_visualshadernodevectorrefract.rst b/classes/class_visualshadernodevectorrefract.rst index 62308f321..066f04237 100644 --- a/classes/class_visualshadernodevectorrefract.rst +++ b/classes/class_visualshadernodevectorrefract.rst @@ -16,7 +16,7 @@ Returns the :ref:`Vector3` that points in the direction of refrac Description ----------- -Translated to ``refract(I, N, eta)`` in the shader language, where ``I`` is the incident vector, ``N`` is the normal vector and ``eta`` is the ratio of the indicies of the refraction. +Translated to ``refract(I, N, eta)`` in the shader language, where ``I`` is the incident vector, ``N`` is the normal vector and ``eta`` is the ratio of the indices of the refraction. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_webrtcpeerconnection.rst b/classes/class_webrtcpeerconnection.rst index 9d44f5def..bd7ee94fd 100644 --- a/classes/class_webrtcpeerconnection.rst +++ b/classes/class_webrtcpeerconnection.rst @@ -38,13 +38,13 @@ Methods +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`close` **(** **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`WebRTCDataChannel` | :ref:`create_data_channel` **(** :ref:`String` label, :ref:`Dictionary` options={ } **)** | +| :ref:`WebRTCDataChannel` | :ref:`create_data_channel` **(** :ref:`String` label, :ref:`Dictionary` options={ } **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`create_offer` **(** **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`ConnectionState` | :ref:`get_connection_state` **(** **)** |const| | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`initialize` **(** :ref:`Dictionary` configuration={ } **)** | +| :ref:`Error` | :ref:`initialize` **(** :ref:`Dictionary` configuration={ } **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`poll` **(** **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -132,7 +132,7 @@ Close the peer connection and all data channels associated with it. Note, you ca .. _class_WebRTCPeerConnection_method_create_data_channel: -- :ref:`WebRTCDataChannel` **create_data_channel** **(** :ref:`String` label, :ref:`Dictionary` options={ } **)** +- :ref:`WebRTCDataChannel` **create_data_channel** **(** :ref:`String` label, :ref:`Dictionary` options={ } **)** Returns a new :ref:`WebRTCDataChannel` (or ``null`` on failure) with given ``label`` and optionally configured via the ``options`` dictionary. This method can only be called when the connection is in state :ref:`STATE_NEW`. @@ -178,7 +178,7 @@ Returns the connection state. See :ref:`ConnectionState` **initialize** **(** :ref:`Dictionary` configuration={ } **)** +- :ref:`Error` **initialize** **(** :ref:`Dictionary` configuration={ } **)** Re-initialize this peer connection, closing any previously active connection, and going back to state :ref:`STATE_NEW`. A dictionary of ``options`` can be passed to configure the peer connection. diff --git a/classes/class_webxrinterface.rst b/classes/class_webxrinterface.rst new file mode 100644 index 000000000..f309bd6bb --- /dev/null +++ b/classes/class_webxrinterface.rst @@ -0,0 +1,429 @@ +:github_url: hide + +.. Generated automatically by doc/tools/makerst.py in Godot's source tree. +.. DO NOT EDIT THIS FILE, but the WebXRInterface.xml source instead. +.. The source is found in doc/classes or modules//doc_classes. + +.. _class_WebXRInterface: + +WebXRInterface +============== + +**Inherits:** :ref:`ARVRInterface` **<** :ref:`Reference` **<** :ref:`Object` + +AR/VR interface using WebXR. + +Description +----------- + +WebXR is an open standard that allows creating VR and AR applications that run in the web browser. + +As such, this interface is only available when running in an HTML5 export. + +WebXR supports a wide range of devices, from the very capable (like Valve Index, HTC Vive, Oculus Rift and Quest) down to the much less capable (like Google Cardboard, Oculus Go, GearVR, or plain smartphones). + +Since WebXR is based on Javascript, it makes extensive use of callbacks, which means that ``WebXRInterface`` is forced to use signals, where other AR/VR interfaces would instead use functions that return a result immediately. This makes ``WebXRInterface`` quite a bit more complicated to intialize than other AR/VR interfaces. + +Here's the minimum code required to start an immersive VR session: + +:: + + extends Spatial + + var webxr_interface + var vr_supported = false + + func _ready(): + # We assume this node has a button as a child. + # This button is for the user to consent to entering immersive VR mode. + $Button.connect("pressed", self, "_on_Button_pressed") + + webxr_interface = ARVRServer.find_interface("WebXR") + if webxr_interface: + # WebXR uses a lot of asynchronous callbacks, so we connect to various + # signals in order to receive them. + webxr_interface.connect("session_supported", self, "_webxr_session_supported") + webxr_interface.connect("session_started", self, "_webxr_session_started") + webxr_interface.connect("session_ended", self, "_webxr_session_ended") + webxr_interface.connect("session_failed", self, "_webxr_session_failed") + + # This returns immediately - our _webxr_session_supported() method + # (which we connected to the "session_supported" signal above) will + # be called sometime later to let us know if it's supported or not. + webxr_interface.is_session_supported("immersive-vr") + + func _webxr_session_supported(session_mode, supported): + if session_mode == 'immersive-vr': + vr_supported = supported + + func _on_Button_pressed(): + if not vr_supported: + OS.alert("Your browser doesn't support VR") + return + + # We want an immersive VR session, as opposed to AR ('immersive-ar') or a + # simple 3DoF viewer ('viewer'). + webxr_interface.session_mode = 'immersive-vr' + # 'bounded-floor' is room scale, 'local-floor' is a standing or sitting + # experience (it puts you 1.6m above the ground if you have 3DoF headset), + # whereas as 'local' puts you down at the ARVROrigin. + # This list means it'll first try to request 'bounded-floor', then + # fallback on 'local-floor' and ultimately 'local', if nothing else is + # supported. + webxr_interface.requested_reference_space_types = 'bounded-floor, local-floor, local' + # In order to use 'local-floor' or 'bounded-floor' we must also + # mark the features as required or optional. + webxr_interface.required_features = 'local-floor' + webxr_interface.optional_features = 'bounded-floor' + + # This will return false if we're unable to even request the session, + # however, it can still fail asynchronously later in the process, so we + # only know if it's really succeeded or failed when our + # _webxr_session_started() or _webxr_session_failed() methods are called. + if not webxr_interface.initialize(): + OS.alert("Failed to initialize") + return + + func _webxr_session_started(): + $Button.visible = false + # This tells Godot to start rendering to the headset. + get_viewport().arvr = true + # This will be the reference space type you ultimately got, out of the + # types that you requested above. This is useful if you want the game to + # work a little differently in 'bounded-floor' versus 'local-floor'. + print ("Reference space type: " + webxr_interface.reference_space_type) + + func _webxr_session_ended(): + $Button.visible = true + # If the user exits immersive mode, then we tell Godot to render to the web + # page again. + get_viewport().arvr = false + + func _webxr_session_failed(message): + OS.alert("Failed to initialize: " + message) + +There are several ways to handle "controller" input: + +- Using :ref:`ARVRController` nodes and their :ref:`ARVRController.button_pressed` and :ref:`ARVRController.button_release` signals. This is how controllers are typically handled in AR/VR apps in Godot, however, this will only work with advanced VR controllers like the Oculus Touch or Index controllers, for example. The buttons codes are defined by `Section 3.3 of the WebXR Gamepads Module `_. + +- Using :ref:`Node._unhandled_input` and :ref:`InputEventJoypadButton` or :ref:`InputEventJoypadMotion`. This works the same as normal joypads, except the :ref:`InputEvent.device` starts at 100, so the left controller is 100 and the right controller is 101, and the button codes are also defined by `Section 3.3 of the WebXR Gamepads Module `_. + +- Using the :ref:`select`, :ref:`squeeze` and related signals. This method will work for both advanced VR controllers, and non-traditional "controllers" like a tap on the screen, a spoken voice command or a button press on the device itself. The ``controller_id`` passed to these signals is the same id as used in :ref:`ARVRController.controller_id`. + +You can use one or all of these methods to allow your game or app to support a wider or narrower set of devices and input methods, or to allow more advanced interations with more advanced devices. + +Tutorials +--------- + +- `https://www.snopekgames.com/blog/2020/how-make-vr-game-webxr-godot `_ + +Properties +---------- + ++-------------------------------------------------+-------------------------------------------------------------------------------------------------------+ +| :ref:`PoolVector3Array` | :ref:`bounds_geometry` | ++-------------------------------------------------+-------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`optional_features` | ++-------------------------------------------------+-------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`reference_space_type` | ++-------------------------------------------------+-------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`requested_reference_space_types` | ++-------------------------------------------------+-------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`required_features` | ++-------------------------------------------------+-------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`session_mode` | ++-------------------------------------------------+-------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`visibility_state` | ++-------------------------------------------------+-------------------------------------------------------------------------------------------------------+ + +Methods +------- + ++-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`ARVRPositionalTracker` | :ref:`get_controller` **(** :ref:`int` controller_id **)** |const| | ++-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`is_session_supported` **(** :ref:`String` session_mode **)** | ++-----------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------+ + +Signals +------- + +.. _class_WebXRInterface_signal_reference_space_reset: + +- **reference_space_reset** **(** **)** + +Emitted to indicate that the reference space has been reset or reconfigured. + +When (or whether) this is emitted depends on the user's browser or device, but may include when the user has changed the dimensions of their play space (which you may be able to access via :ref:`bounds_geometry`) or pressed/held a button to recenter their position. + +See `WebXR's XRReferenceSpace reset event `_ for more information. + +---- + +.. _class_WebXRInterface_signal_select: + +- **select** **(** :ref:`int` controller_id **)** + +Emitted after one of the "controllers" has finished its "primary action". + +Use :ref:`get_controller` to get more information about the controller. + +---- + +.. _class_WebXRInterface_signal_selectend: + +- **selectend** **(** :ref:`int` controller_id **)** + +Emitted when one of the "controllers" has finished its "primary action". + +Use :ref:`get_controller` to get more information about the controller. + +---- + +.. _class_WebXRInterface_signal_selectstart: + +- **selectstart** **(** :ref:`int` controller_id **)** + +Emitted when one of the "controllers" has started its "primary action". + +Use :ref:`get_controller` to get more information about the controller. + +---- + +.. _class_WebXRInterface_signal_session_ended: + +- **session_ended** **(** **)** + +Emitted when the user ends the WebXR session (which can be done using UI from the browser or device). + +At this point, you should do ``get_viewport().arvr = false`` to instruct Godot to resume rendering to the screen. + +---- + +.. _class_WebXRInterface_signal_session_failed: + +- **session_failed** **(** :ref:`String` message **)** + +Emitted by :ref:`ARVRInterface.initialize` if the session fails to start. + +``message`` may optionally contain an error message from WebXR, or an empty string if no message is available. + +---- + +.. _class_WebXRInterface_signal_session_started: + +- **session_started** **(** **)** + +Emitted by :ref:`ARVRInterface.initialize` if the session is successfully started. + +At this point, it's safe to do ``get_viewport().arvr = true`` to instruct Godot to start rendering to the AR/VR device. + +---- + +.. _class_WebXRInterface_signal_session_supported: + +- **session_supported** **(** :ref:`String` session_mode, :ref:`bool` supported **)** + +Emitted by :ref:`is_session_supported` to indicate if the given ``session_mode`` is supported or not. + +---- + +.. _class_WebXRInterface_signal_squeeze: + +- **squeeze** **(** :ref:`int` controller_id **)** + +Emitted after one of the "controllers" has finished its "primary squeeze action". + +Use :ref:`get_controller` to get more information about the controller. + +---- + +.. _class_WebXRInterface_signal_squeezeend: + +- **squeezeend** **(** :ref:`int` controller_id **)** + +Emitted when one of the "controllers" has finished its "primary squeeze action". + +Use :ref:`get_controller` to get more information about the controller. + +---- + +.. _class_WebXRInterface_signal_squeezestart: + +- **squeezestart** **(** :ref:`int` controller_id **)** + +Emitted when one of the "controllers" has started its "primary squeeze action". + +Use :ref:`get_controller` to get more information about the controller. + +---- + +.. _class_WebXRInterface_signal_visibility_state_changed: + +- **visibility_state_changed** **(** **)** + +Emitted when :ref:`visibility_state` has changed. + +Property Descriptions +--------------------- + +.. _class_WebXRInterface_property_bounds_geometry: + +- :ref:`PoolVector3Array` **bounds_geometry** + ++----------+-----------------------+ +| *Getter* | get_bounds_geometry() | ++----------+-----------------------+ + +The vertices of a polygon which defines the boundaries of the user's play area. + +This will only be available if :ref:`reference_space_type` is ``"bounded-floor"`` and only on certain browsers and devices that support it. + +The :ref:`reference_space_reset` signal may indicate when this changes. + +---- + +.. _class_WebXRInterface_property_optional_features: + +- :ref:`String` **optional_features** + ++----------+------------------------------+ +| *Setter* | set_optional_features(value) | ++----------+------------------------------+ +| *Getter* | get_optional_features() | ++----------+------------------------------+ + +A comma-seperated list of optional features used by :ref:`ARVRInterface.initialize` when setting up the WebXR session. + +If a user's browser or device doesn't support one of the given features, initialization will continue, but you won't be able to use the requested feature. + +This doesn't have any effect on the interface when already initialized. + +Possible values come from `WebXR's XRReferenceSpaceType `_. If you want to use a particular reference space type, it must be listed in either :ref:`required_features` or :ref:`optional_features`. + +---- + +.. _class_WebXRInterface_property_reference_space_type: + +- :ref:`String` **reference_space_type** + ++----------+----------------------------+ +| *Getter* | get_reference_space_type() | ++----------+----------------------------+ + +The reference space type (from the list of requested types set in the :ref:`requested_reference_space_types` property), that was ultimately used by :ref:`ARVRInterface.initialize` when setting up the WebXR session. + +Possible values come from `WebXR's XRReferenceSpaceType `_. If you want to use a particular reference space type, it must be listed in either :ref:`required_features` or :ref:`optional_features`. + +---- + +.. _class_WebXRInterface_property_requested_reference_space_types: + +- :ref:`String` **requested_reference_space_types** + ++----------+--------------------------------------------+ +| *Setter* | set_requested_reference_space_types(value) | ++----------+--------------------------------------------+ +| *Getter* | get_requested_reference_space_types() | ++----------+--------------------------------------------+ + +A comma-seperated list of reference space types used by :ref:`ARVRInterface.initialize` when setting up the WebXR session. + +The reference space types are requested in order, and the first on supported by the users device or browser will be used. The :ref:`reference_space_type` property contains the reference space type that was ultimately used. + +This doesn't have any effect on the interface when already initialized. + +Possible values come from `WebXR's XRReferenceSpaceType `_. If you want to use a particular reference space type, it must be listed in either :ref:`required_features` or :ref:`optional_features`. + +---- + +.. _class_WebXRInterface_property_required_features: + +- :ref:`String` **required_features** + ++----------+------------------------------+ +| *Setter* | set_required_features(value) | ++----------+------------------------------+ +| *Getter* | get_required_features() | ++----------+------------------------------+ + +A comma-seperated list of required features used by :ref:`ARVRInterface.initialize` when setting up the WebXR session. + +If a user's browser or device doesn't support one of the given features, initialization will fail and :ref:`session_failed` will be emitted. + +This doesn't have any effect on the interface when already initialized. + +Possible values come from `WebXR's XRReferenceSpaceType `_. If you want to use a particular reference space type, it must be listed in either :ref:`required_features` or :ref:`optional_features`. + +---- + +.. _class_WebXRInterface_property_session_mode: + +- :ref:`String` **session_mode** + ++----------+-------------------------+ +| *Setter* | set_session_mode(value) | ++----------+-------------------------+ +| *Getter* | get_session_mode() | ++----------+-------------------------+ + +The session mode used by :ref:`ARVRInterface.initialize` when setting up the WebXR session. + +This doesn't have any effect on the interface when already initialized. + +Possible values come from `WebXR's XRSessionMode `_, including: ``"immersive-vr"``, ``"immersive-ar"``, and ``"inline"``. + +---- + +.. _class_WebXRInterface_property_visibility_state: + +- :ref:`String` **visibility_state** + ++----------+------------------------+ +| *Getter* | get_visibility_state() | ++----------+------------------------+ + +Indicates if the WebXR session's imagery is visible to the user. + +Possible values come from `WebXR's XRVisibilityState `_, including ``"hidden"``, ``"visible"``, and ``"visible-blurred"``. + +Method Descriptions +------------------- + +.. _class_WebXRInterface_method_get_controller: + +- :ref:`ARVRPositionalTracker` **get_controller** **(** :ref:`int` controller_id **)** |const| + +Gets an :ref:`ARVRPositionalTracker` for the given ``controller_id``. + +In the context of WebXR, a "controller" can be an advanced VR controller like the Oculus Touch or Index controllers, or even a tap on the screen, a spoken voice command or a button press on the device itself. When a non-traditional controller is used, interpret the position and orientation of the :ref:`ARVRPositionalTracker` as a ray pointing at the object the user wishes to interact with. + +Use this method to get information about the controller that triggered one of these signals: + +- :ref:`selectstart` + +- :ref:`select` + +- :ref:`selectend` + +- :ref:`squeezestart` + +- :ref:`squeeze` + +- :ref:`squeezestart` + +---- + +.. _class_WebXRInterface_method_is_session_supported: + +- void **is_session_supported** **(** :ref:`String` session_mode **)** + +Checks if the given ``session_mode`` is supported by the user's browser. + +Possible values come from `WebXR's XRSessionMode `_, including: ``"immersive-vr"``, ``"immersive-ar"``, and ``"inline"``. + +This method returns nothing, instead it emits the :ref:`session_supported` signal with the result. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_world.rst b/classes/class_world.rst index 44539d8ef..052fda108 100644 --- a/classes/class_world.rst +++ b/classes/class_world.rst @@ -49,7 +49,7 @@ Property Descriptions | *Getter* | get_direct_space_state() | +----------+--------------------------+ -Direct access to the world's physics 3D space state. Used for querying current and potential collisions. Must only be accessed from within ``_physics_process(delta)``. +Direct access to the world's physics 3D space state. Used for querying current and potential collisions. ---- diff --git a/classes/class_world2d.rst b/classes/class_world2d.rst index 0b7dd0857..94d1fd662 100644 --- a/classes/class_world2d.rst +++ b/classes/class_world2d.rst @@ -57,7 +57,7 @@ The :ref:`RID` of this world's canvas resource. Used by the :ref:`Vis | *Getter* | get_direct_space_state() | +----------+--------------------------+ -Direct access to the world's physics 2D space state. Used for querying current and potential collisions. Must only be accessed from the main thread within ``_physics_process(delta)``. +Direct access to the world's physics 2D space state. Used for querying current and potential collisions. When using multi-threaded physics, access is limited to ``_physics_process(delta)`` in the main thread. ---- diff --git a/classes/class_worldenvironment.rst b/classes/class_worldenvironment.rst index 49d6516b4..8dad7abfb 100644 --- a/classes/class_worldenvironment.rst +++ b/classes/class_worldenvironment.rst @@ -27,6 +27,12 @@ Tutorials - :doc:`../tutorials/3d/environment_and_post_processing` +- `https://godotengine.org/asset-library/asset/123 `_ + +- `https://godotengine.org/asset-library/asset/110 `_ + +- `https://godotengine.org/asset-library/asset/678 `_ + Properties ----------