Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Évaluation des expressions

Godot fournit une classe Expression que vous pouvez utiliser pour évaluer des expressions.

Une expression peut être :

  • Une expression mathématique comme (2 + 4) * 16/4.0.

  • A built-in method call like deg_to_rad(90).

  • Un appel de méthode sur un script fourni par l'utilisateur comme update_health(), si base_instance est défini à une valeur autre que null lors de l'appel Expression.execute().

Note

La classe Expression est indépendante de GDScript. Elle est disponible même si vous compilez Godot avec le module GDScript désactivé.

Utilisation de base

Pour évaluer une expression mathématique, utilisez : :

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

Les opérateurs suivants sont disponibles :

Opérateur

Notes

Addition +

Peut également être utilisé pour concaténer des chaînes de caractères et des tableaux : - "hello" + " world" = hello world - [1, 2] + [3, 4] = [1, 2, 3, 4]

Soustraction (-)

Multiplication (*)

Division (/)

Effectue une division entière si les deux opérandes sont des entiers. Si au moins l'un d'entre eux est un nombre à virgule flottante, renvoie une valeur à virgule flottante.

Module (%)

Retourne le reste d'une division entière.

Les espaces autour des opérateurs sont facultatifs. Gardez également à l'esprit que l'ordre habituel des opérations <https://en.wikipedia.org/wiki/Order_of_operations>`__ s'applique. Utilisez les parenthèses pour remplacer l'ordre des opérations si nécessaire.

Tous les types de variantes pris en charge par Godot peuvent être utilisés : entiers, nombres à virgule flottante, chaînes de caractères, tableaux, dictionnaires, couleurs, vecteurs, …

Les tableaux et les dictionnaires peuvent être indexés comme dans 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

Passage de variables à une expression

Vous pouvez passer des variables à une expression. Ces variables seront alors disponibles dans le "contexte" de l'expression et seront substituées lorsqu'elles seront utilisées dans l'expression : :

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

Les noms et les valeurs des variables doivent être spécifiés sous forme de tableau, même si vous ne définissez qu'une seule variable. En outre, les noms de variables sont sensibles à la casse.

Définition d'une instance de base pour l'expression

Par défaut, une expression à une instance de base à null. Ceci veut dire que l'expression n'a aucune instance qui lui est associée.

Lorsque vous appelez Expression.execute(), vous pouvez définir la valeur du paramètre base_instance sur une instance d'objet spécifique telle que self, une autre instance de script ou même un singleton : :

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

Associer une instance de base permet de faire ceci :

  • Référence la constante (const) de l'instance dans l'expression.

  • Référence la variable (var) de l'instance dans l'expression.

  • Appelez les méthodes définies dans l'instance et utilisez leurs valeurs de retour dans l'expression.

Avertissement

Donner à une instance de base une valeur autre que null permet de référencer les constantes, les variables membres et d'appeler toutes les méthodes définies dans le script attaché à l'instance. Autoriser les utilisateurs à saisir des expressions peut permettre la tricherie dans votre jeu, ou peut même introduire des failles de sécurité si vous autorisez des clients arbitraires à exécuter des expressions sur les appareils des autres joueurs.

Exemple de script

Le script ci-dessous démontre ce dont la classe Expression est capable : :

const DAYS_IN_YEAR = 365
var script_member_variable = 1000


func _ready():
    # 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

La sortie depuis le script sera : :

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

Fonctions intégrées

All methods in the Global Scope are available in the Expression class, even if no base instance is bound to the expression. The same parameters and return types are available.

Cependant, contrairement au GDScript, les paramètres sont toujours obligatoires même s'ils sont spécifiés comme étant facultatifs dans la référence de la classe. En revanche, cette restriction sur les arguments ne s'applique pas aux fonctions créées par l'utilisateur lorsque vous liez une instance de base à l'expression.