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

Valutazione delle espressioni

Godot fornisce una classe Expression che si può utilizzare per valutare le espressioni.

Un'espressione può essere:

Un'espressione matematica come (2 + 4) * 16/4.0.
Un'espressione booleana come true && false.
Una chiamata a un metodo integrato come deg_to_rad(90).
Una chiamata a un metodo su uno script fornito dall'utente come update_health(), se base_instance è impostato su un valore diverso da null quando si chiama Expression.execute().

Nota

La classe Expression è indipendente da GDScript. È disponibile anche se si compila Godot con il modulo GDScript disabilitato.

Utilizzo di base

Per valutare un'espressione matematica, utilizzare:

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

Sono disponibili i seguenti operatori:

Operatore	Note
Addizione `+`	Si può anche utilizzare per concatenare stringhe e array: - `"hello" + " world"` = `hello world` - `[1, 2] + [3, 4]` = `[1, 2, 3, 4]`
Sottrazione (`-`)
Moltiplicazione (`*`)
Divisione (`/`)	Effettua una divisione intera se entrambi gli operandi sono interi. Se almeno uno di essi è un numero in virgola mobile, restituisce un valore in virgola mobile.
Resto (`%`)	Restituisce il resto di una divisione intera (modulo). Il risultato avrà sempre il segno del dividendo.
Congiunzione (`&&`)	Restituisce il risultato di un AND booleano.
Disgiunzione (`\|\|`)	Restituisce il risultato di un OR booleano.
Negazione (`!`)	Restituisce il risultato di un NOT booleano.

Gli spazi tra gli operatori sono facoltativi. Inoltre, tenere presente che si applica il solito ordine delle operazioni. Se necessario, usare le parentesi per sovrascrivere l'ordine delle operazioni.

È possibile usare tutti i tipi di Variant supportati in Godot: interi, numeri in virgola mobile, stringhe, array, dizionari, colori, vettori, …

Array e dizionari si possono indicizzare come 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

Passare variabili a un'espressione

È possibile passare variabili a un'espressione. Queste variabili diventeranno quindi disponibili nel "contesto" dell'espressione e verranno sostituite quando utilizzate nell'espressione:

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

Entrambi i nomi e i valori delle variabili devono essere specificati come array, anche se si definisce una sola variabile. Inoltre, i nomi delle variabili sono sensibili alle maiuscole e alle minuscole.

Impostare un'istanza base per l'espressione

Come predefinito, un'espressione ha un'istanza base null. Ciò significa che all'espressione non è associata alcuna istanza base.

Quando si chiama Expression.execute(), è possibile impostare il valore del parametro base_instance su un'istanza specifica di un oggetto come self, un'altra istanza di script o anche 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

Associating a base instance allows doing the following:

Fare riferimento alle costanti (const) dell'istanza nell'espressione.
Fare riferimento alle variabili membro (var) dell'istanza nell'espressione.
Chiamare i metodi definiti nell'istanza e utilizzare i loro valori restituiti nell'espressione.

Avvertimento

Impostare un'istanza base su un valore diverso da null consente di fare riferimento a costanti, variabili membro e di chiamare tutti i metodi definiti nello script associato all'istanza. Consentire agli utenti di inserire espressioni potrebbe consentire di barare nel gioco o persino introdurre vulnerabilità di sicurezza se si consente a client arbitrari di eseguire espressioni sui dispositivi di altri giocatori.

Script di esempio

Lo script seguente dimostra le capacità della classe 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

Il risultato dello script sarà:

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

Funzioni integrate

Tutti i metodi nell'ambito globale sono disponibili nella classe Expression, anche se nessuna istanza base è associata all'espressione. Sono disponibili gli stessi parametri e tipi restituiti.

Tuttavia, a differenza di GDScript, i parametri sono sempre obbligatori anche se specificati come facoltativi nel riferimento alla classe. Al contrario, tale restrizione sugli argomenti non si applica alle funzioni create dall'utente quando si associa un'istanza base all'espressione.