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...

É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.
Une expression booléenne comme true && false .
A built-in method call like deg_to_rad(90).
A method call on a user-provided script like update_health(), if base_instance is set to a value other than null when calling 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

To evaluate a mathematical expression, use:

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.
Reste (`%`)	Renvoie le reste d'une division entière (modulo). Le résultat aura toujours le signe du dividende.
Conjunction (`&&`)	Returns the result of a boolean AND.
Disjonction (`\|\|`)	Returns the result of a boolean OR.
Negation (`!`)	Returns the result of a boolean NOT.

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, …

Arrays and dictionaries can be indexed like in 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

You can pass variables to an expression. These variables will then become available in the expression's "context" and will be substituted when used in the 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.

When calling Expression.execute(), you can set the value of the base_instance parameter to a specific object instance such as self, another script instance or even a 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

The script below demonstrates what the Expression class is capable of:

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

The output from the script will be:

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

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.