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

Engine

Eredita: Object

Fornisce accesso alle proprietà del motore.

Descrizione

Il singleton Engine consente di interrogare e modificare i parametri di esecuzione del progetto, come frame al secondo, scala temporale e altri. Memorizza anche informazioni sulla build attuale di Godot, come la versione attuale.

Proprietà

int	max_fps	`0`
int	max_physics_steps_per_frame	`8`
float	physics_jitter_fix	`0.5`
int	physics_ticks_per_second	`60`
bool	print_error_messages	`true`
bool	print_to_stdout	`true`
float	time_scale	`1.0`

Metodi

Array[ScriptBacktrace]	capture_script_backtraces(include_variables: bool = false) const
String	get_architecture_name() const
Dictionary	get_author_info() const
Array[Dictionary]	get_copyright_info() const
Dictionary	get_donor_info() const
int	get_frames_drawn()
float	get_frames_per_second() const
Dictionary	get_license_info() const
String	get_license_text() const
MainLoop	get_main_loop() const
int	get_physics_frames() const
float	get_physics_interpolation_fraction() const
int	get_process_frames() const
ScriptLanguage	get_script_language(index: int) const
int	get_script_language_count()
Object	get_singleton(name: StringName) const
PackedStringArray	get_singleton_list() const
Dictionary	get_version_info() const
String	get_write_movie_path() const
bool	has_singleton(name: StringName) const
bool	is_editor_hint() const
bool	is_embedded_in_editor() const
bool	is_in_physics_frame() const
Error	register_script_language(language: ScriptLanguage)
void	register_singleton(name: StringName, instance: Object)
Error	unregister_script_language(language: ScriptLanguage)
void	unregister_singleton(name: StringName)

Descrizioni delle proprietà

int max_fps = 0 🔗

void set_max_fps(value: int)
int get_max_fps()

The maximum number of frames that can be rendered every second (FPS). A value of 0 means the framerate is uncapped.

Limiting the FPS can be useful to reduce the host machine's power consumption, which reduces heat, noise emissions, and improves battery life.

If ProjectSettings.display/window/vsync/vsync_mode is Enabled or Adaptive, the setting takes precedence and the max FPS number cannot exceed the monitor's refresh rate. See also DisplayServer.screen_get_refresh_rate().

If ProjectSettings.display/window/vsync/vsync_mode is Enabled, on monitors with variable refresh rate enabled (G-Sync/FreeSync), using an FPS limit a few frames lower than the monitor's refresh rate will reduce input lag while avoiding tearing. At higher refresh rates, the difference between the FPS limit and the monitor refresh rate should be increased to ensure frames to account for timing inaccuracies. The optimal formula for the FPS limit value in this scenario is r - (r * r) / 3600.0, where r is the monitor's refresh rate.

Note: The actual number of frames per second may still be below this value if the CPU or GPU cannot keep up with the project's logic and rendering.

Note: If ProjectSettings.display/window/vsync/vsync_mode is Disabled, limiting the FPS to a high value that can be consistently reached on the system can reduce input lag compared to an uncapped framerate. Since this works by ensuring the GPU load is lower than 100%, this latency reduction is only effective in GPU-bottlenecked scenarios, not CPU-bottlenecked scenarios.

int max_physics_steps_per_frame = 8 🔗

void set_max_physics_steps_per_frame(value: int)
int get_max_physics_steps_per_frame()

Numero massimo di passaggi di fisica che possono essere simulati per ogni frame renderizzato.

Nota: Il valore predefinito è regolato per impedire che costose simulazioni di fisica inneschino simulazioni ancora più costose all'infinito. Tuttavia, il gioco sembrerà rallentare se l'FPS di rendering è inferiore a 1 / max_physics_steps_per_frame di physics_ticks_per_second. Ciò si verifica anche se delta è utilizzato costantemente nei calcoli della fisica. Per evitarlo, aumenta max_physics_steps_per_frame se hai aumentato physics_ticks_per_second drasticamente al di sopra del suo valore predefinito.

float physics_jitter_fix = 0.5 🔗

void set_physics_jitter_fix(value: float)
float get_physics_jitter_fix()

Quanti tick di fisica sono sincronizzati con il tempo reale. Se 0 o meno, i tick sono completamente sincronizzati. Valori più alti causano una maggiore deviazione dell'orologio di gioco dall'orologio reale, ma attenuano le instabilità del frame rate.

Nota: Il valore predefinito di 0.5 dovrebbe essere accettabile per la maggior parte dei casi; valori superiori a 2 potrebbero portare a una reazione ai frame persi con un ritardo notevole e non sono consigliati.

Nota: Quando si utilizza una soluzione di interpolazione fisica personalizzata o all'interno di un gioco in rete, si consiglia di disabilitare la correzione di instabilità della fisica impostando questa proprietà su 0.

int physics_ticks_per_second = 60 🔗

void set_physics_ticks_per_second(value: int)
int get_physics_ticks_per_second()

The number of fixed iterations per second. This controls how often physics simulation and the Node._physics_process() method are run.

CPU usage scales approximately with the physics tick rate. However, at very low tick rates (usually below 30), physics behavior can break down. Input can also become less responsive at low tick rates as there can be a gap between input being registered, and the response on the next physics tick. High tick rates give more accurate physics simulation, particularly for fast moving objects. For example, racing games may benefit from increasing the tick rate above the default 60.

Note: Only max_physics_steps_per_frame physics ticks may be simulated per rendered frame at most. If more physics ticks have to be simulated per rendered frame to keep up with rendering, the project will appear to slow down (even if delta is used consistently in physics calculations). Therefore, it is recommended to also increase max_physics_steps_per_frame if increasing physics_ticks_per_second significantly above its default value.

Note: Consider enabling physics interpolation if you change physics_ticks_per_second to a value that is not a multiple of 60. Using physics interpolation will avoid jittering when the monitor refresh rate and physics update rate don't exactly match.

bool print_error_messages = true 🔗

void set_print_error_messages(value: bool)
bool is_printing_error_messages()

Se false, blocca la stampa di messaggi di errore e di avviso nella console e nel registro di output dell'editor. Può essere utilizzato per nascondere messaggi di errore e di avviso durante l'esecuzione di unit test suite. Questa proprietà è equivalente all'impostazione del progetto ProjectSettings.application/run/disable_stderr.

Nota: Questa proprietà non influisce sulla scheda Errori dell'editor quando si esegue un progetto dall'editor.

Attenzione: Se impostato su false in qualsiasi punto del progetto, i messaggi di errore importanti potrebbero essere nascosti anche se sono emessi da altri script. In uno script @tool, ciò avrà un impatto anche sull'editor stesso. Non segnalare bug prima di assicurarti che i messaggi di errore siano abilitati (come lo sono per impostazione predefinita).

bool print_to_stdout = true 🔗

void set_print_to_stdout(value: bool)
bool is_printing_to_stdout()

Se false, smette di stampare i messaggi (ad esempio tramite @GlobalScope.print()) nella console, nei file di log e nel log di output nell'editor. Questa proprietà è equivalente all'impostazione del progetto ProjectSettings.application/run/disable_stdout.

Nota: Questo non smette di stampare gli errori o avvisi prodotti dagli script nella console o nei file di log, per maggiori dettagli vedi print_error_messages.

float time_scale = 1.0 🔗

void set_time_scale(value: float)
float get_time_scale()

Il moltiplicatore di velocità a cui si aggiorna l'orologio di gioco, rispetto al tempo reale. Ad esempio, se impostato su 2.0 il gioco è eseguito due volte più velocemente, e se impostato su 0.5 il gioco è eseguito due volte più lentamente.

Questo valore influenza Timer, SceneTreeTimer, e tutte le altre simulazioni che utilizzano il tempo delta (come Node._process() e Node._physics_process()).

Nota: Si consiglia di mantenere questa proprietà maggiore di 0.0, altrimenti il gioco potrebbe comportarsi in modo imprevisto.

Nota: Questo non influenza la velocità di riproduzione audio. Usa AudioServer.playback_speed_scale per regolare la velocità di riproduzione audio indipendentemente da time_scale.

Nota: Questo non regola automaticamente physics_ticks_per_second. Con valori superiori a 1.0 la simulazione fisica potrebbe diventare meno precisa, poiché ogni tick di fisica si estenderà su un periodo di tempo del motore più ampio. Se stai modificando time_scale per velocizzare la simulazione di un fattore elevato, considera anche di aumentare physics_ticks_per_second per rendere la simulazione più affidabile.

Descrizioni dei metodi

Array[ScriptBacktrace] capture_script_backtraces(include_variables: bool = false) const 🔗

Cattura e restituisce backtrace da tutti i linguaggi di script registrati.

Come predefinito, il ScriptBacktrace restituito conterrà gli stack frame solo nelle build dell'editor e nelle build di debug. Per abilitarli anche per le build di rilascio, è necessario abilitare ProjectSettings.debug/settings/gdscript/always_track_call_stacks.

Se include_variables è true, il backtrace includerà anche i nomi e i valori di eventuali variabili globali (ad esempio, singleton autoload) al momento della cattura, nonché le variabili locali e le variabili membro delle classi in ogni stack frame. Questo, tuttavia, sarà rispettato solo quando si esegue il gioco con un debugger collegato, ad esempio quando si esegue il gioco dall'editor. Per abilitarlo anche per le build di esportazione, è necessario abilitare ProjectSettings.debug/settings/gdscript/always_track_local_variables.

Attenzione: Quando include_variables è true, qualsiasi variabile catturata può potenzialmente (ad esempio con i backtrace GDScript) essere il suo valore effettivo, inclusi eventuali riferimenti agli oggetti. Ciò significa che memorizzare tale ScriptBacktrace impedirà di deallocare tali oggetti, quindi in genere si consiglia di non farlo.

String get_architecture_name() const 🔗

Restituisce il nome dell'architettura della CPU per il quale è stato creato l'eseguibile di Godot. I possibili valori restituiti includono "x86_64", "x86_32", "arm64", "arm32", "rv64", "ppc64", "loongarch64", "wasm64" e "wasm32".

Per individuare se la build attuale è a 64 bit, o il tipo di architettura, non usare il nome dell'architettura. Invece, usa OS.has_feature() per controllare il tag di funzionalità "64", oppure tag come "x86" o "arm". Consulta la documentazione dei tag di funzionalità per ulteriori dettagli.

Nota: Questo metodo non restituisce il nome dell'architettura CPU del sistema (come OS.get_processor_name()). Ad esempio, quando si esegue un binario Godot x86_32 su un sistema x86_64, il valore restituito sarà comunque "x86_32".

Dictionary get_author_info() const 🔗

Restituisce le informazioni sugli autori del motore come un Dictionary, dove ogni voce è un Array di stringhe con i nomi dei collaboratori più importanti del Godot Engine: lead_developers, founders, project_managers, e developers.

Array[Dictionary] get_copyright_info() const 🔗

Restituisce un Array di dizionari con informazioni sul copyright per ogni componente del codice sorgente di Godot.

Ogni Dictionary contiene un identificatore name e un array parts di dizionari. Quest'ultimo descrive il componente in dettaglio con le seguenti voci:

files - Array di percorsi di file dal codice sorgente interessati da questo componente;
copyright - Array di proprietari di questo componente;
license - La licenza applicata a questo componente (ad esempio "Expat" o "CC-BY-4.0").

Dictionary get_donor_info() const 🔗

Restituisce un Dictionary di nomi categorizzati dei donatori. Ogni voce è un Array di stringhe:

{platinum_sponsors, gold_sponsors, silver_sponsors, bronze_sponsors, mini_sponsors, gold_donors, silver_donors, bronze_donors}

int get_frames_drawn() 🔗

Restituisce il numero totale di frame disegnati dall'avvio del motore.

Nota: Sulle piattaforme headless, o se il rendering è disabilitato con --disable-render-loop tramite riga di comando, questo metodo restituisce sempre 0. Vedi anche get_process_frames().

float get_frames_per_second() const 🔗

Restituisce la media dei fotogrammi renderizzati ogni secondo (FPS), nota anche come frequenza dei fotogrammi.

Dictionary get_license_info() const 🔗

Restituisce un Dictionary di licenze utilizzate da Godot e componenti di terze parti incluse. Ogni voce è un nome di licenza (ad esempio "Expat") e il suo testo associato.

String get_license_text() const 🔗

Restituisce il testo completo della licenza di Godot.

MainLoop get_main_loop() const 🔗

Restituisce l'istanza del MainLoop. Di solito è il SceneTree principale ed è uguale a Node.get_tree().

Nota: Il tipo istanziato come ciclo principale può essere modificato con ProjectSettings.application/run/main_loop_type.

int get_physics_frames() const 🔗

Restituisce il numero totale di frame passati dall'avvio del motore. Questo numero aumenta ogni frame di fisica. Vedi anche get_process_frames().

Questo metodo può essere utilizzato per eseguire la logica costosa meno spesso senza fare affidamento su un Timer:

func _physics_process(_delta):
    if Engine.get_physics_frames() % 2 == 0:
        pass # Esegui la logica costosa solo una volta ogni 2 frame di fisica qui.

public override void _PhysicsProcess(double delta)
{
    base._PhysicsProcess(delta);

    if (Engine.GetPhysicsFrames() % 2 == 0)
    {
        // Esegui la logica costosa solo una volta ogni 2 frame di fisica qui.
    }
}

float get_physics_interpolation_fraction() const 🔗

Restituisce la frazione attraverso il tick di fisica attuale in cui ci troviamo al momento del rendering del frame. Può essere utilizzato per implementare un'interpolazione di passo fisso.

int get_process_frames() const 🔗

Restituisce il numero totale di frame passati dall'avvio del motore. Questo numero aumenta ogni frame di processo, indipendentemente dal fatto che il ciclo di rendering sia abilitato. Vedi anche get_frames_drawn() e get_physics_frames().

Questo metodo può essere utilizzato per eseguire la logica costosa meno spesso senza fare affidamento su un Timer:

func _process(_delta):
    if Engine.get_process_frames() % 5 == 0:
        pass # Esegui la logica costosa solo una volta ogni 5 frame di processo (rendering) qui.

public override void _Process(double delta)
{
    base._Process(delta);

    if (Engine.GetProcessFrames() % 5 == 0)
    {
        // Esegui la logica costosa solo una volta ogni 5 frame di processo (rendering) qui.
    }
}

ScriptLanguage get_script_language(index: int) const 🔗

Restituisce un'istanza di ScriptLanguage con l'indice index.

int get_script_language_count() 🔗

Restituisce il numero di linguaggi di script disponibili. Da utilizzare con get_script_language().

Object get_singleton(name: StringName) const 🔗

Restituisce il singleton globale con il nome name, o null se non esiste. Spesso utilizzato per le estensioni. Vedi anche has_singleton() e get_singleton_list().

Nota: I singleton globali non sono la stessa cosa dei nodi autoload, che sono configurabili nelle Impostazioni del progetto.

PackedStringArray get_singleton_list() const 🔗

Restituisce una lista di nomi di tutti i singleton globali disponibili. Vedi anche get_singleton().

Dictionary get_version_info() const 🔗

Restituisce le informazioni sulla versione corrente del motore come un Dictionary contenente le seguenti voci:

major - Numero di versione principale come int;
minor - Numero di versione secondaria come int;
patch - Numero di versione della patch come int;
hex - Versione completa codificata come int esadecimale con un byte (2 cifre esadecimali) per numero (vedi l'esempio di seguito);
status - Stato (ad esempio "beta", "rc1", "rc2", "stable", ecc.) come String;
build - Nome della build (ad esempio "custom_build") come String;
hash - Hash completo del commit Git come String;
timestamp - Contiene la data di commit Git, timestamp UNIX in secondi come int, o 0 se non disponibile;
string - major, minor, patch, status, e build in una singola stringa.

Il valore hex è codificato come segue, da sinistra a destra: un byte per il major, un byte per il minor, un byte per la versione di patch. Ad esempio, "3.1.12" sarebbe 0x03010C.

Nota: Il valore hex è comunque un int internamente e stampandolo otterrai la sua rappresentazione decimale, che non è particolarmente utile. Usa i letterali esadecimali per rapidi confronti di versione da codice:

if Engine.get_version_info().hex >= 0x040100:
    pass # Esegue azioni specifiche per la versione 4.1 o successive.
else:
    pass # Esegue azioni specifiche per le versioni precedenti alla 4.1.

if ((int)Engine.GetVersionInfo()["hex"] >= 0x040100)
{
    // Esegue azioni specifiche per la versione 4.1 o successive.
}
else
{
    // Esegue azioni specifiche per le versioni precedenti alla 4.1.
}

String get_write_movie_path() const 🔗

Restituisce il percorso al file di output di MovieWriter, oppure una stringa vuota se il motore non è stato avviato in modalità Movie Maker. Il percorso predefinito può essere modificato in ProjectSettings.editor/movie_writer/movie_file.

bool has_singleton(name: StringName) const 🔗

Restituisce true se un singleton con il nome name esiste nell'ambito globale. Vedi anche get_singleton().

print(Engine.has_singleton("OS"))          # Stampa true
print(Engine.has_singleton("Engine"))      # Stampa true
print(Engine.has_singleton("AudioServer")) # Stampa true
print(Engine.has_singleton("Unknown"))     # Stampa false

GD.Print(Engine.HasSingleton("OS"));          // Stampa True
GD.Print(Engine.HasSingleton("Engine"));      // Stampa True
GD.Print(Engine.HasSingleton("AudioServer")); // Stampa True
GD.Print(Engine.HasSingleton("Unknown"));     // Stampa False

Nota: I singleton globali non sono la stessa cosa dei nodi autoload, che sono configurabili nelle impostazioni del progetto.

bool is_editor_hint() const 🔗

Restituisce true se lo script è attualmente in esecuzione all'interno dell'editor, altrimenti restituisce false. Ciò è utile per gli script @tool per disegnare in modo condizionale gli helper dell'editor o impedire l'esecuzione accidentale di codice "di gioco" che potrebbe influenzare lo stato della scena mentre è attiva nell'editor:

if Engine.is_editor_hint():
    draw_gizmos()
else:
    simulate_physics()

if (Engine.IsEditorHint())
    DrawGizmos();
else
    SimulatePhysics();

Vedi Esecuzione di codice nell'editor nella documentazione per ulteriori informazioni.

Nota: Per rilevare se lo script è in esecuzione su una build dall'editor (ad esempio quando si preme F5), usa invece OS.has_feature() con l'argomento "editor". OS.has_feature("editor") restituisce true sia quando lo script è in esecuzione nell'editor sia quando si esegue il progetto dall'editor, ma restituisce false quando viene chiamato da un progetto esportato.

bool is_embedded_in_editor() const 🔗

Restituisce true se il motore è in esecuzione incorporato nell'editor. Ciò è utile per evitare di tentare di aggiornare la modalità o i flag di una finestra che non sono supportati quando si esegue il progetto incorporato nell'editor.

bool is_in_physics_frame() const 🔗

Restituisce true se il motore si trova all'interno del passaggio di processo fisso di fisica del ciclo principale.

func _enter_tree():
    # A seconda di quando il nodo viene aggiunto all'albero,
    # stampa "true" o "false".
    print(Engine.is_in_physics_frame())

func _process(delta):
    print(Engine.is_in_physics_frame()) # Stampa false

func _physics_process(delta):
    print(Engine.is_in_physics_frame()) # Stampa true

Error register_script_language(language: ScriptLanguage) 🔗

Registra un'istanza di ScriptLanguage da rendere disponibile con ScriptServer.

Restituisce:

@GlobalScope.OK in caso di successo;
@GlobalScope.ERR_UNAVAILABLE se ScriptServer ha raggiunto il limite e non può registrare alcuna nuova lingua;
@GlobalScope.ERR_ALREADY_EXISTS se ScriptServer contiene già una lingua con simile estensione, nome, o tipo.

void register_singleton(name: StringName, instance: Object) 🔗

Registra l'Object instance specificato come singleton, disponibile globalmente con il nome name. Utile per le estensioni.

Error unregister_script_language(language: ScriptLanguage) 🔗

Annulla la registrazione dell'istanza ScriptLanguage da ScriptServer.

Restituisce:

@GlobalScope.OK in caso di successo;
@GlobalScope.ERR_DOES_NOT_EXIST se la lingua non è registrata in ScriptServer.

void unregister_singleton(name: StringName) 🔗

Rimuove il singleton registrato con il nome name. L'oggetto singleton non è liberato. Funziona solo con singleton definiti dall'utente registrati con register_singleton().