Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Обчислення виразів

Godot надає клас Expression, який можна використовувати для обчислення виразів.

Вираз може бути:

• Математичний вираз, такий як (2 + 4) * 16/4.0.

• Логічний вираз, наприклад true && false.

• Виклик вбудованого методу, наприклад deg_to_rad(90).

• Виклик методу наданого користувачем сценарію, наприклад update_health(), якщо base_instance під час виклику встановлюється значення, відмінне від null Expression.execute().

Примітка

Клас Expression не залежить від GDScript. Він доступний, навіть якщо ви збираєте Godot з вимкненим модулем GDScript.

Базове використання

Щоб обчислити математичний вираз, використовуйте:

var expression = Expression.new()
expression.parse("20 + 10*2 - 5/2.0")
var result = expression.execute()
print(result)  # 37.5

Доступні такі оператори:

Оператор	Нотатки
Додавання +	Також можна використовувати для об’єднання рядків і масивів: - "hello" + " world" = hello world - [1, 2] + [3, 4] = [1 , 2, 3, 4]
Віднімання (-)
Множення (*)
Ділення (/)	Виконує цілочисельне ділення, якщо обидва операнди є цілими. Якщо хоча б одне з них є числом з плаваючою комою, повертає значення з плаваючою комою.
Залишок (%)	Повертає залишок від цілого ділення (за модулем). Результат завжди матиме знак дивіденду.
Сполучник (&&)	Повертає результат логічного І.
Диз'юнкція (||)	Повертає результат логічного АБО.
Заперечення (!)	Повертає результат логічного значення NOT.

Пробіли навколо операторів необов’язкові. Також пам’ятайте, що застосовується звичайний порядок операцій. Використовуйте дужки, щоб замінити порядок операцій, якщо це необхідно.

Можна використовувати всі типи Variant, які підтримуються Godot: цілі числа, числа з плаваючою комою, рядки, масиви, словники, кольори, вектори, …

Масиви та словники можна індексувати, як у GDScript:

# Returns 1.
[1, 2][0]

# Returns 3. Negative indices can be used to count from the end of the array.
[1, 3][-1]

# Returns "green".
{"favorite_color": "green"}["favorite_color"]

# All 3 lines below return 7.0 (Vector3 is floating-point).
Vector3(5, 6, 7)[2]
Vector3(5, 6, 7)["z"]
Vector3(5, 6, 7).z

Передача змінних у вираз

Ви можете передавати змінні до виразу. Ці змінні стануть доступними в "контексті" виразу та будуть підставлені під час використання у виразі:

var expression = Expression.new()
# Define the variable names first in the second parameter of `parse()`.
# In this example, we use `x` for the variable name.
expression.parse("20 + 2 * x", ["x"])
# Then define the variable values in the first parameter of `execute()`.
# Here, `x` is assigned the integer value 5.
var result = expression.execute([5])
print(result)  # 30

І назви змінних, і значення змінних повинні вказуватися як масив, навіть якщо ви визначаєте лише одну змінну. Крім того, імена змінних чутливі до регістру.

Встановлення базового екземпляра для виразу

За замовчуванням вираз має базовий екземпляр null. Це означає, що вираз не має пов’язаного з ним базового екземпляра.

Під час виклику Expression.execute() ви можете встановити значення параметра base_instance для певного екземпляра об'єкта, такого як self, інший екземпляр скрипта або навіть синглтон:

func double(number):
    return number * 2


func _ready():
    var expression = Expression.new()
    expression.parse("double(10)")

    # This won't work since we're not passing the current script as the base instance.
    var result = expression.execute([], null)
    print(result)  # null

    # This will work since we're passing the current script (i.e. self)
    # as the base instance.
    result = expression.execute([], self)
    print(result)  # 20

Зв’язування базового екземпляра дозволяє виконувати такі дії:

• Посилання на константи екземпляра (const) у виразі.

• Посилання на змінні-члени екземпляра (var) у виразі.

• Викликати методи, визначені в екземплярі, і використовувати їх значення, що повертаються, у виразі.

Попередження

Встановлення для базового екземпляра значення, відмінного від null, дозволяє посилатися на константи, змінні-члени та викликати всі методи, визначені в сценарії, прикріпленому до екземпляра. Якщо дозволити користувачам вводити вирази, це може призвести до шахрайства у вашій грі або навіть створити вразливі місця в безпеці, якщо ви дозволите довільним клієнтам запускати вирази на пристроях інших гравців.

Приклад сценарію

Наведений нижче скрипт демонструє можливості класу Expression:

const DAYS_IN_YEAR = 365
var script_member_variable = 1000


func _ready():
    # Constant boolean expression.
    evaluate("true && false")
    # Boolean expression with variables.
    evaluate("!(a && b)", ["a", "b"], [true, false])

    # Constant mathexpression.
    evaluate("2 + 2")
    # Math expression with variables.
    evaluate("x + y", ["x", "y"], [60, 100])

    # Call built-in method (built-in math function call).
    evaluate("deg_to_rad(90)")

    # Call user method (defined in the script).
    # We can do this because the expression execution is bound to `self`
    # in the `evaluate()` method.
    # Since this user method returns a value, we can use it in math expressions.
    evaluate("call_me() + DAYS_IN_YEAR + script_member_variable")
    evaluate("call_me(42)")
    evaluate("call_me('some string')")


func evaluate(command, variable_names = [], variable_values = []) -> void:
    var expression = Expression.new()
    var error = expression.parse(command, variable_names)
    if error != OK:
        push_error(expression.get_error_text())
        return

    var result = expression.execute(variable_values, self)

    if not expression.has_execute_failed():
        print(str(result))


func call_me(argument = null):
    print("\nYou called 'call_me()' in the expression text.")
    if argument:
        print("Argument passed: %s" % argument)

    # The method's return value is also the expression's return value.
    return 0

Вивід скрипта буде таким:

false
true
4
160
1.5707963267949

You called 'call_me()' in the expression text.
1365

You called 'call_me()' in the expression text.
Argument passed: 42
0

You called 'call_me()' in the expression text.
Argument passed: some string
0

Вбудовані функції

Усі методи в Global Scope доступні в класі Expression, навіть якщо жоден базовий екземпляр не прив’язаний до виразу. Доступні однакові параметри та типи повернення.

Однак, на відміну від GDScript, параметри завжди є обов’язковими, навіть якщо вони вказані як необов’язкові в посиланні на клас. Навпаки, це обмеження на аргументи не застосовується до створених користувачами функцій, коли ви прив’язуєте базовий екземпляр до виразу.