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

Passare da Godot 4.4 a Godot 4.5

Per la maggior parte dei giochi e delle applicazioni creati in 4.4, dovrebbe essere relativamente sicuro migrare a 4.5. Questa pagina intende illustrare tutti gli aspetti a cui prestare attenzione durante la migrazione del proprio progetto.

Modifiche incompatibili

Se stai migrando dalla versione 4.4 alla 4.5, le modifiche incompatibili elencate qui potrebbero interessarti. Le modifiche sono raggruppate per aree/sistemi.

Avvertimento

Per supportare new Google Play requirements, Android ora richiede di utilizzare .NET 9 quando si esportano progetti C# su Android; altre piattaforme continuano a utilizzare .NET 8 come versione minima richiesta, ma le versioni più recenti sono supportate e consigliate.

Se si utilizza C# nel proprio progetto e si desidera esportarlo su Android, sarà necessario aggiornare il progetto a .NET 9 (Consultare Upgrading to a new .NET version per le istruzioni).

Questo articolo indica se ogni modifica incompatibile influisce su GDScript e se una modifica incompatibile in C# è compatibile con il binario o compatibile con il codice sorgente:

• Compatibile con gli eseguibili - Gli eseguibili esistenti saranno caricati ed eseguiti correttamente senza doverli ricompilare, e il comportamento in fase di esecuzione non cambierà.

• Compatibile con il codice sorgente - Il codice sorgente sarà compilato correttamente senza cambiamenti all'aggiornamento di Godot.

Fondamentali

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
JSONRPC
Il metodo set_scope è stato sostituito da set_method	❌	❌	❌	GH-104890
Node
Il metodo get_rpc_config è stato rinominato in get_node_rpc_config	❌	✔️	✔️	GH-106848
Il metodo set_name cambia il tipo del parametro name da String a StringName	✔️	✔️	✔️	GH-76560

Renderer

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
DisplayServer
Il metodo file_dialog_show aggiunge un nuovo parametro facoltativo parent_window_id	✔️	✔️	✔️	GH-98194
Il metodo file_dialog_with_options_show aggiunge un nuovo parametro facoltativo backward_undo_ops	✔️	✔️	✔️	GH-98194
RenderingDevice
Il metodo texture_create_from_extension aggiunge un nuovo parametro facoltativo mipmaps	✔️	✔️	✔️	GH-105570
RenderingServer
Metodo instance_reset_physics_interpolation rimosso	❌	✔️	✔️	GH-104269
Metodo instance_set_interpolated rimosso	❌	✔️	✔️	GH-104269

Nota

In C#, l'enumerazione RenderingDevice.Features interrompe la compatibilità a causa del modo in cui il generatore di binding rileva il prefisso dell'enumerazione. In GH-103941 sono stati aggiunti nuovi membri all'enum, causando il membro Address a essere rinominato in BufferDeviceAddress.

GLTF

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
GLTFAccessor
La proprietà byte_offset cambia il tipo di metadati da int32 a int64	✔️	❌	❌	GH-106220
La proprietà component_type cambia tipo da int a GLTFAccessor::GLTFComponentType	✔️	❌	❌	GH-106220
La proprietà count cambia il tipo di metadati da int32 a int64	✔️	❌	❌	GH-106220
La proprietà sparse_count cambia il tipo di metadati da int32 a int64	✔️	❌	❌	GH-106220
La proprietà sparse_indices_byte_offset cambia il tipo di metadati da int32 a int64	✔️	❌	❌	GH-106220
La proprietà sparse_indices_component_type cambia tipo da int a GLTFAccessor::GLTFComponentType	✔️	❌	❌	GH-106220
La proprietà sparse_values_byte_offset cambia il tipo di metadati da int32 a int64	✔️	❌	❌	GH-106220
GLTFBufferView
La proprietà byte_length cambia il tipo di metadati da int32 a int64	✔️	❌	❌	GH-106220
La proprietà byte_offset cambia il tipo di metadati da int32 a int64	✔️	❌	❌	GH-106220
La proprietà byte_stride cambia il tipo di metadati da int32 a int64	✔️	❌	❌	GH-106220

Nota

A causa di cambiamenti dei metadati di tipo, i binding C# hanno cambiato il tipo da int (32 byte) a long (64 byte).

Testo

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
CanvasItem
Il metodo draw_char aggiunge un nuovo parametro facoltativo free_submenus	✔️	✔️	✔️	GH-104872
Il metodo draw_char_outline aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo draw_multiline_string aggiunge un nuovo parametro facoltativo backward	✔️	✔️	✔️	GH-104872
Il metodo draw_multiline_string_outline aggiunge un nuovo parametro facoltativo backward	✔️	✔️	✔️	GH-104872
Il metodo draw_string aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo draw_string_outline aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Font
Il metodo draw_char aggiunge un nuovo parametro facoltativo free_submenus	✔️	✔️	✔️	GH-104872
Il metodo draw_char_outline aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo draw_multiline_string aggiunge un nuovo parametro facoltativo backward	✔️	✔️	✔️	GH-104872
Il metodo draw_multiline_string_outline aggiunge un nuovo parametro facoltativo backward	✔️	✔️	✔️	GH-104872
Il metodo draw_string aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo draw_string_outline aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
RichTextLabel
Il metodo add_image aggiunge un nuovo parametro facoltativo alt_text	✔️	✔️	✔️	GH-76829
Il metodo add_image ha sostituito il parametro size_in_percent con width_in_percent e height_in_percent	✔️	✔️	✔️	GH-107347
Il metodo push_strikethrough aggiunge un nuovo parametro facoltativo parameter	✔️	✔️	✔️	GH-106300
Il metodo push_table aggiunge un nuovo parametro facoltativo name	✔️	✔️	✔️	GH-76829
Il metodo push_underline aggiunge un nuovo parametro facoltativo color	✔️	✔️	✔️	GH-106300
Il metodo update_image ha sostituito il parametro size_in_percent con width_in_percent e height_in_percent	✔️	✔️	✔️	GH-107347
TextLine
Il metodo draw aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo track_find_key aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
TextParagraph
Il metodo draw aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo draw_dropcap aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo draw_dropcap_outline aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo draw_line aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo draw_line_outline aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo track_find_key aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
TextServer
Il metodo font_draw_glyph aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo font_draw_glyph_outline aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo shaped_text_draw aggiunge un nuovo parametro facoltativo oversampling	✔️	✔️	✔️	GH-104872
Il metodo shaped_text_draw_outline aggiunge un nuovo parametro facoltativo msaa	✔️	✔️	✔️	GH-104872
TreeItem
Il metodo add_button aggiunge un nuovo parametro facoltativo alt_text	✔️	✔️	✔️	GH-76829
TextServerExtension
Il metodo _font_draw_glyph aggiunge un nuovo parametro facoltativo oversampling	❌	❌	❌	GH-104872
Il metodo _font_draw_glyph_outline aggiunge un nuovo parametro facoltativo oversampling	❌	❌	❌	GH-104872
Il metodo _shaped_text_draw aggiunge un nuovo parametro facoltativo oversampling	❌	❌	❌	GH-104872
Il metodo _shaped_text_draw_outline aggiunge un nuovo parametro facoltativo oversampling	❌	❌	❌	GH-104872

XR

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
OpenXRAPIExtension
Il metodo register_composition_layer_provider cambia il tipo del parametro extension da OpenXRExtensionWrapperExtension a OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
Il metodo register_projection_views_extension cambia il tipo del parametro extension da OpenXRExtensionWrapperExtension a uint64	✔️	✔️	✔️	GH-104087
Il metodo unregister_composition_layer_provider cambia il tipo del parametro extension da OpenXRExtensionWrapperExtension a OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
Il metodo _post_process_key_value cambia il tipo del parametro extension da OpenXRExtensionWrapperExtension a OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
OpenXRBindingModifierEditor
Il tipo OpenXRBindingModifierEditor cambia il tipo di API da Core a Editor	❌	❌	❌	GH-103869
OpenXRInteractionProfileEditor
Il tipo OpenXRInteractionProfileEditor cambia il tipo di API da Core a Editor	❌	❌	❌	GH-103869
OpenXRInteractionProfileEditorBase
Il tipo OpenXRInteractionProfileEditorBase cambia il tipo di API da Core a Editor	❌	❌	❌	GH-103869

Nota

Le classi OpenXRBindingModifierEditor, OpenXRInteractionProfileEditor e OpenXRInteractionProfileEditorBase sono disponibili solo nell'editor. Il loro utilizzo al di fuori dell'editor causerà un errore di compilazione.

In C#, questo significa che i tipi sono stati spostati dall'assembly GodotSharp all'assembly GodotSharpEditor. Assicurarsi di racchiudere il codice che utilizza questi tipi in un blocco #if TOOLS per evitare che siano inclusi in un gioco esportato.

Questo cambiamento è stata retroportato anche alla versione 4.4.1.

Estensioni per l'editor

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
EditorExportPlatform
Il metodo get_forced_export_files aggiunge un nuovo parametro facoltativo preset	✔️	✔️	✔️	GH-71542
EditorUndoRedoManager
Il metodo create_action aggiunge un nuovo parametro facoltativo mark_unsaved	✔️	✔️	✔️	GH-106121
EditorExportPlatformExtension
Il metodo _get_option_icon cambia il tipo restituito da ImageTexture a Texture2D	✔️	❌	❌	GH-108825

Cambiamenti di comportamento

Nella versione 4.5 sono state introdotte alcune modifiche comportamentali che potrebbero richiedere di adattare i propri progetti.

TileMapLayer

TileMapLayer.get_coords_for_body_rid() restituirà valori diversi nella in 4.5 rispetto a 4.4, poiché la suddivisione in blocchi fisica (physics chunking) di TileMapLayer è abilitata come predefinito. Valori più alti di TileMapLayer.physics_quadrant_size renderanno questa funzione meno precisa. Per ottenere le coordinate esatte di una cella come nella versione 4.4 e precedenti, è necessario impostare TileMapLayer.physics_quadrant_size su 1, il che disabilita la suddivisione fisica.

Importazione di modelli 3D

È stata apportata una correzione agli importatori di modelli 3D per gestire correttamente i nodi (esclusi i giunti) dentro una gerarchia di uno scheletro (GH-104184). Per preservare la compatibilità, il comportamento predefinito è quello di importare i file esistenti con lo stesso comportamento di prima (GH-107352). I nuovi file .gltf, .glb, .blend e .fbx (senza un file .import corrispondente) saranno importati con il nuovo comportamento. Tuttavia, per i file esistenti, se si desidera utilizzare il nuovo comportamento, è necessario cambiare l'opzione "Naming Version" in basso al pannello di importazione:

Fondamentali

Nota

Resource.duplicate(true) (che effettua una duplicazione profonda) ora duplica solo le risorse interne al file di risorse su cui viene chiamato. Nella versione 4.4, invece, duplicava tutto, comprese le risorse esterne. Se si stava effettuando una duplicazione profonda di una risorsa che conteneva riferimenti ad altre risorse esterne, queste ultime non vengono più duplicate. È necessario chiamare Resource.duplicate_deep(DEEP_DUPLICATE_ALL) per mantenere il comportamento precedente.

Nota

ProjectSettings.add_property_info() ora stampa un avviso quando il parametro dizionario ha chiavi mancanti o chiavi non valide. Ancora più importante, ora emetterà un avviso quando viene passata una chiave usage, poiché questa chiave non viene utilizzata. Questo accadeva anche prima della versione 4.5, ma era ignorato silenziosamente. Come promemoria, per impostare correttamente le informazioni sull'uso delle proprietà, è necessario utilizzare ProjectSettings.set_as_basic(), ProjectSettings.set_restart_if_changed() oppure ProjectSettings.set_as_internal().

Nota

In C#, StringExtensions.PathJoin ora evita di aggiungere un separatore di percorso in più quando la stringa originale è vuota o quando il percorso aggiunto inizia con un separatore di percorso (GH-105281).

Nota

In C#, StringExtensions.GetExtension ora restituisce una stringa vuota anziché la stringa originale quando la stringa originale non contiene un'estensione (GH-108041).

Nota

In C#, il costruttore Quaternion(Vector3, Vector3) ora crea correttamente un quaternione che rappresenta l'arco più breve tra i due vettori di input. In passato, restituiva valori errati per alcuni input (GH-107618).

Navigazione

Nota

Come predefinito, le regioni in una mappa nel NavigationServer vengono aggiornate in modo asincrono attraverso i thread per migliorare le prestazioni. Ciò può causare un ulteriore ritardo nell'aggiornamento a causa della sincronizzazione dei thread. È possibile abilitare o disabilitare l'aggiornamento asincrono delle regioni tramite l'impostazione del progetto navigation/world/region_use_async_iterations.

Nota

L'unione delle navmesh nel NavigationServer ha cambiato l'ordine di elaborazione. Ora le regioni uniscono e memorizzano nella cache prima le navmesh interne, poi i bordi liberi rimanenti vengono uniti dalla mappa di navigazione. Se un progetto prima aveva errori di sincronizzazione nella mappa di navigazione, ora potrebbe aver spostato i bordi interessati, rendendo più evidenti gli errori già presenti nella disposizione durante la ricerca di percorsi. L'impostazione del progetto navigation/2d_or_3d/merge_rasterizer_cell_scale può essere impostata su un valore inferiore per aumentare il dettaglio della griglia di rasterizzazione (essendo 0.01 la dimensione minima delle celle). Se gli errori di unione dei bordi persistono anche con il valore di scala di rasterizzazione più basso possibile, l'errore potrebbe essere causato da una sovrapposizione: due navmesh sono impilate una sopra l'altra, causando un conflitto geometrico.

Fisica

Nota

Quando il motore di fisica 3D è impostato su Jolt Physics, saranno sempre riportate le sovrapposizioni tra Area3D e i corpi statici, poiché l'impostazione del progetto physics/jolt_physics_3d/simulation/areas_detect_static_bodies è stata rimossa (GH-105746). Se si desidera comunque ignorare tali sovrapposizioni, sarà necessario modificare la maschera di collisione o gli strati dell'Area3D o del corpo statico.

Testo

Nota

In GDScript, le chiamate alle funzioni RichTextLabel::add_image e RichTextLabel::update_image continueranno a funzionare, ma l'argomento size_in_percent sarà ora utilizzato come valore per width_in_percent e height_in_percent, che sarà predefinito su false (GH-107347). Per ripristinare il comportamento precedente, è possibile impostare esplicitamente height_in_percent sullo stesso valore passato in size_in_percent.