Up to date

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

Evaluating expressions¶

Godot provides an Expression class you can use to evaluate expressions.

An expression can be:

A mathematical expression such as (2 + 4) * 16/4.0.
A built-in method call like deg_to_rad(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.

Basic usage¶

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

The following operators are available:

Operator	Notes
Addition `+`	Can also be used to concatenate strings and arrays: - `"hello" + " world"` = `hello world` - `[1, 2] + [3, 4]` = `[1, 2, 3, 4]`
Subtraction (`-`)
Multiplication (`*`)
Division (`/`)	Performs and integer division if both operands are integers. If at least one of them is a floating-point number, returns a floating-point value.
Modulo (`%`)	Returns the remainder of an integer division.

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:

# 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

Passing variables to an 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

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.

Setting a base instance for the expression¶

By default, an expression has a base instance of null. This means the expression has no base instance associated to it.

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