Evaluating expressions

    An expression can be:

    • A mathematical expression such as .

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

    • A method call on an user-provided script like update_health(), if base_instance is set to a value other than null when calling Expression.execute().

    Note

    The Expression class is independent from GDScript. It’s available even if you compile Godot with the GDScript module disabled.

    To evaluate a mathematical expression, use:

    The following operators are available:

    Spaces around operators are optional. Also, keep in mind the usual order of operations applies. Use parentheses to override the order of operations if needed.

    All the Variant types supported in Godot can be used: integers, floating-point numbers, strings, arrays, dictionaries, colors, vectors, …

    Arrays and dictionaries can be indexed like in GDScript:

    1. # Returns 1.
    2. [1, 2][0]
    4. # Returns 3. Negative indices can be used to count from the end of the array.
    5. [1, 3][-1]
    7. # Returns "green".
    10. Vector3(5, 6, 7)[2]
    11. Vector3(5, 6, 7)["z"]
    12. Vector3(5, 6, 7).z

    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:

    Both the variable names and variable values must be specified as an array, even if you only define one variable. Also, variable names are case-sensitive.

    When calling , 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:

    1. func double(number):
    2.     return number * 2
    5. func _ready():
    6.     var expression = Expression.new()
    7.     expression.parse("double(10)")
    9.     # This won't work since we're not passing the current script as the base instance.
    10.     var result = expression.execute([], null)
    11.     print(result)  # null
    14.     # as the base instance.
    15.     print(result)  # 20

    Associating a base instance allows doing the following:

    • Reference the instance’s constants (const) in the expression.

    • Reference the instance’s member variables (var) in the expression.

    • Call methods defined in the instance and use their return values in the expression.

    Warning

    Setting a base instance to a value other than null allows referencing constants, member variables, and calling all methods defined in the script attached to the instance. Allowing users to enter expressions may allow cheating in your game, or may even introduce security vulnerabilities if you allow arbitrary clients to run expressions on other players’ devices.

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

    The output from the script will be:

    1. 4
    2. 160
    3. 1.570796
    5. You called 'call_me()' in the expression text.
    6. 1365
    8. You called 'call_me()' in the expression text.
    9. Argument passed: 42
    10. 0
    12. You called 'call_me()' in the expression text.
    13. Argument passed: some string

    Most methods available in the @GDScript 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.

    However, unlike GDScript, parameters are always required even if they’re specified as being optional in the class reference. In contrast, this restriction on arguments doesn’t apply to user-made functions when you bind a base instance to the expression.