godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-04 14:11:02 +03:00
Code Issues Packages Projects Releases Wiki Activity

classref: Sync with current 3.x branch

Browse Source
This commit is contained in:
Rémi Verschelde
2021-04-07 11:23:16 +02:00
parent 3b76cc3b54
commit 0e2c601163
264 changed files with 4824 additions and 1245 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
classes/class_@gdscript.rst
View File

@@ -170,7 +170,7 @@ Methods
+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>` | :ref:`sinh<class_@GDScript_method_sinh>` **(** :ref:`float<class_float>` s **)** |
+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>` | :ref:`smoothstep<class_@GDScript_method_smoothstep>` **(** :ref:`float<class_float>` from, :ref:`float<class_float>` to, :ref:`float<class_float>` weight **)** |
| :ref:`float<class_float>` | :ref:`smoothstep<class_@GDScript_method_smoothstep>` **(** :ref:`float<class_float>` from, :ref:`float<class_float>` to, :ref:`float<class_float>` s **)** |
+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>` | :ref:`sqrt<class_@GDScript_method_sqrt>` **(** :ref:`float<class_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<class_float>` **acos** **(** :ref:`float<class_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<class_@GDScript_method_acos>` will return :ref:`NAN<class_@GDScript_constant_NAN>`.
::
@@ -293,7 +292,7 @@ Returns the arc cosine of ``s`` in radians. Use to get the angle of cosine ``s``
- :ref:`float<class_float>` **asin** **(** :ref:`float<class_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<class_@GDScript_method_asin>` will return :ref:`NAN<class_@GDScript_constant_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<class_bool>` condition, :ref:`String<class_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<class_@GDScript_method_push_error>` for reporting errors to project developers or add-on users.
**Note:** For performance reasons, the code inside :ref:`assert<class_@GDScript_method_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<class_@GDScript_method_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<class_@GDScript_method_floor>`, :ref:`round<class_@GDScript_method_round>`, and :ref:`stepify<class_@GDScript_method_stepify>`.
See also :ref:`floor<class_@GDScript_method_floor>`, :ref:`round<class_@GDScript_method_round>`, :ref:`stepify<class_@GDScript_method_stepify>`, and :ref:`int<class_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<class_Object>` **dict2inst** **(** :ref:`Dictionary<class_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<class_@GDScript_method_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<class_@GDScript_method_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<class_@GDScript_method_ceil>`, :ref:`round<class_@GDScript_method_round>`, and :ref:`stepify<class_@GDScript_method_stepify>`.
See also :ref:`ceil<class_@GDScript_method_ceil>`, :ref:`round<class_@GDScript_method_round>`, :ref:`stepify<class_@GDScript_method_stepify>`, and :ref:`int<class_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<class_ResourceLoader_method_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<class_int>` **nearest_po2** **(** :ref:`int<class_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<class_float>` **pow** **(** :ref:`float<class_float>` base, :ref:`float<class_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<class_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<class_@GDScript_method_push_error>` and :ref:`push_warning<class_@GDScript_method_push_warning>` to print error and warning messages instead of :ref:`print<class_@GDScript_method_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<class_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<class_@GDScript_method_floor>`, :ref:`ceil<class_@GDScript_method_ceil>`, and :ref:`stepify<class_@GDScript_method_stepify>`.
See also :ref:`floor<class_@GDScript_method_floor>`, :ref:`ceil<class_@GDScript_method_ceil>`, :ref:`stepify<class_@GDScript_method_stepify>`, and :ref:`int<class_int>`.
----
@@ -1279,13 +1293,18 @@ Returns the hyperbolic sine of ``s``.
.. _class_@GDScript_method_smoothstep:
- :ref:`float<class_float>` **smoothstep** **(** :ref:`float<class_float>` from, :ref:`float<class_float>` to, :ref:`float<class_float>` weight **)**
- :ref:`float<class_float>` **smoothstep** **(** :ref:`float<class_float>` from, :ref:`float<class_float>` to, :ref:`float<class_float>` s **)**
Returns a number smoothly interpolated between the ``from`` and ``to``, based on the ``weight``. Similar to :ref:`lerp<class_@GDScript_method_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<class_@GDScript_method_ceil>`, :ref:`floor<class_@GDScript_method_floor>`, and :ref:`round<class_@GDScript_method_round>`.
See also :ref:`ceil<class_@GDScript_method_ceil>`, :ref:`floor<class_@GDScript_method_floor>`, :ref:`round<class_@GDScript_method_round>`, and :ref:`int<class_int>`.
----
@@ -1341,7 +1357,7 @@ See also :ref:`ceil<class_@GDScript_method_ceil>`, :ref:`floor<class_@GDScript_m
- :ref:`String<class_String>` **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
----