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 3 a Godot 4

Dovrei passare a Godot 4?

Prima di cominciare il processo di aggiornamento, vale la pena riflettere sui vantaggi e sugli svantaggi che tale operazione comporterebbe per il proprio progetto.

Vantaggi dell'aggiornamento

Oltre alle nuove funzionalità presenti nella versione 4.0, l'aggiornamento offre i seguenti vantaggi:

Molti bug sono stati risolti nella versione 4.0, ma non si possono risolvere nella versione 3.x per vari motivi (ad esempio differenze nelle API grafiche o compatibilità con le versioni precedenti).
La versione 4.x godrà di un periodo di supporto più lungo. Godot 3.x continuerà a essere supportato per un po' di tempo dopo il rilascio della versione 4.0, ma eventualmente non riceverà più supporto.

Consultare Changelog della documentazione per un elenco delle pagine che documentano le nuove funzionalità di Godot 4.0 e Elenco delle funzionalità per un elenco di tutte le funzionalità di Godot.

Svantaggi dell'aggiornamento

Se non c'è bisogno di alcuna delle funzionalità presenti in Godot 4.x, sarebbe meglio rimanere su Godot 3.x per i seguenti motivi:

I requisiti hardware di base di Godot 4 (come l'utilizzo della memoria) sono leggermente più elevati, sia per l'editor sia per i progetti esportati. Questo è stato necessario per l'implementazione di alcune ottimizzazioni fondamentali.
Poiché Godot 4 include più funzionalità di Godot 3, le dimensioni dei file binari di Godot 4 per i progetti esportati sono maggiori. Sebbene questo problema possa essere mitigato ottimizzando una build per le dimensioni, una build 4.0 con un dato insieme di moduli abilitati rimarrà più grande rispetto a una build 3.x con gli stessi moduli. Questo può essere un problema per esportare sul Web, poiché le dimensioni dei file binari influenzano direttamente la velocità di inizializzazione del motore (indipendentemente dalla velocità di download).
Godot 4 non supporta e non supporterà il rendering GLES2. (Il supporto per il rendering GLES3 è ancora disponibile utilizzando il nuovo renderer Compatibilità, il che significa che i dispositivi senza supporto per Vulkan possono comunque eseguire Godot 4.)
- Se si punta verso hardware molto vecchio, come una scheda grafica integrata Intel Sandy Bridge (2ª generazione), ciò impedirà al progetto di funzionare su tale hardware dopo l'aggiornamento. Le implementazioni software OpenGL si possono utilizzare per aggirare questa limitazione, ma sono troppo lente per il gioco.

Avvertenze sull'aggiornamento

Dato che Godot 4 è una riscrittura completa sotto molti aspetti, alcune funzionalità sono purtroppo andate perse nel processo. Alcune di queste funzionalità potrebbero essere ripristinate nelle versioni future di Godot:

Bullet physics è stato rimosso a favore di GodotPhysics. Questo riguarda solo i progetti 3D che utilizzavano il motore fisico predefinito (Bullet) e non lo modificavano manualmente in GodotPhysics. Non ci sono piani per aggiungere nuovamente Bullet Physics nel core, ma è possibile creare per esso un componente aggiuntivo di terze parti grazie a GDExtension.
Per impostazione predefinita, il rendering in 2D non viene più eseguito in HDR, il che significa che i valori di modulazione "sovra-luminosi" non hanno alcun effetto visibile. A partire da Godot 4.2, è possibile abilitare l'impostazione del progetto HDR 2D per eseguire il rendering 2D in HDR. Consultare anche Utilizzo di bagliore in 2D.
Sebbene il rendering avvenga ancora in HDR in 3D quando si utilizzano i renderer Forward+ o Mobile, i Viewport non possono più restituire dati in HDR. Si prevede che ciò verrà ripristinato in futuro.
Mono è stato sostituito da .NET 6. Ciò significa che l'esportazione di progetti C# su Android, iOS e HTML5 non è più supportata al momento. L'esportazione di progetti C# su piattaforme desktop è ancora supportata e, a partire dalla versione 4.2, è disponibile un supporto sperimentale per l'esportazione su piattaforme mobili. Il supporto per l'esportazione di progetti C# su altre piattaforme verrà ripristinato nelle future versioni 4.x man mano che il supporto upstream migliorerà.

È possibile trovare un elenco più completo delle regressioni funzionali cercando problemi etichettati come "regression" ma non come "bug" su GitHub.

Preparazione prima dell'aggiornamento (facoltativo)

Per prepararsi ad aggiornare a Godot 4 in futuro, si consiglia l'uso di Tweener e del singleton Time nel proprio progetto. Queste classi sono entrambe disponibili in Godot 3.5 e versioni successive.

In questo modo, non sarà più necessario dipendere dalle funzioni obsolete del nodo Tween e del tempo in OS, rimosse in Godot 4.0.

È anche una buona idea rinominare gli shader esterni in modo che la loro estensione sia .gdshader invece di .shader. Godot 3.x supporta entrambe le estensioni, ma in Godot 4.0 è supportata solo .gdshader.

Eseguire lo strumento di aggiornamento di progetti

Pericolo

Eseguire un backup completo del proprio progetto prima di aggiornare! Lo strumento di aggiornamento di progetto non eseguirà alcun backup del progetto durante l'aggiornamento.

È possibile eseguire il backup di un progetto attraverso il controllo versioni oppure copiando la cartella del progetto da un'altra parte.

Utilizzare il Gestore dei progetti

Per utilizzare lo strumento di aggiornamento di progetti:

Apri il Gestore dei progetti di Godot 4.
Importare il progetto Godot 3.x utilizzando il pulsante Importa oppure utilizzare il pulsante Scansiona per trovare il progetto all'interno di una cartella.
Fare doppio clic sul progetto importato (oppure selezionare il progetto e scegliere Modifica).
Apparirà una finestra di dialogo con due opzioni: Converti solo project.godot e Converti progetto completo. Dopo essersi assicurati che il progetto abbia un backup (vedere l'avviso sopra), scegliere Converti progetto completo. Converti solo project.godot è pensato per essere utilizzato solo in casi di uso avanzato, nel caso in cui lo strumento di conversione non funzioni.
Attendere il completamento del processo di conversione del progetto. Questo può richiedere fino a qualche minuto per progetti grandi con molte scene.
Quando l'interfaccia del Gestore di progetti torna disponibile, fare doppio clic sul progetto (oppure selezionare il progetto e poi scegliere Modifica) per aprirlo nell'editor.

Se si riscontrano problemi di conversione a causa di file di progetto troppo grandi o lunghi, è possibile utilizzare la riga di comando per aggiornare il progetto (vedere sotto). Ciò permetterà di ignorare i limiti di dimensione del convertitore.

Utilizzo della linea di comando

Per utilizzare lo strumento di aggiornamento di progetti dalla riga di comando, si consiglia di convalidare la conversione del progetto avviando l'eseguibile dell'editor Godot con i seguenti argomenti:

# [<max_file_kb>] [<max_line_size>] are optional arguments.
# Remove them if you aren't changing their values.
path/to/godot.binary --path /path/to/project/folder --validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]

Se l'elenco degli aggiornamenti pianificati semba soddisfacente, eseguire il seguente comando sull'eseguibile dell'editor Godot per aggiornare i file del progetto:

# [<max_file_kb>] [<max_line_size>] are optional arguments.
# Remove them if you aren't changing their values.
path/to/godot.binary --path /path/to/project/folder --convert-3to4 [<max_file_kb>] [<max_line_size>]

[<max_file_kb>] e [<max_line_size>] sono argomenti facoltativi per specificare la dimensione massima dei file da convertire (in kilobyte e righe). I limiti predefiniti sono rispettivamente 4 MB e 100.000 righe. Se un file raggiunge uno di questi limiti, non verrà aggiornato dal convertitore di progetto. Questo è utile per evitare che risorse di grandi dimensioni rallentino l'aggiornamento a una scansione.

Se si desidera comunque che i grandi file vengano convertiti dallo strumento di aggiornamento di progetti, è possibile aumentare i limiti di dimensione durante l'esecuzione dello strumento. Ad esempio, avviando l'eseguibile dell'editor Godot con questi argomenti aumenta entrambi i limiti di un fattore 10x:

path/to/godot.binary --path /path/to/project/folder --convert-3to4 40000 1000000

Nota

Solo i progetti Godot 3.0 e successivi si possono aggiornare attraverso lo strumento di conversione dei progetti presente nell'editor Godot 4.

Si consiglia di verificare che il progetto sia aggiornato con l'ultima versione stabile 3.x prima di eseguire lo strumento di aggiornamento dei progetti.

Correggere il progetto dopo l'esecuzione dello strumento di aggiornamento dei progetti

Dopo aver aggiornato il progetto, si potrebbe notare che alcuni elementi non appaiono come dovrebbero. È probabile che anche gli script contengano diversi errori (anche centinaia nei progetti molto grandi). Questo perché lo strumento di aggiornamento dei progetti non è in grado di gestire tutte le situazioni. Pertanto, gran parte del processo di aggiornamento rimane manuale.

Nodi e risorse rinominati automaticamente

L'elenco seguente si riferisce ai nodi che sono stati semplicemente rinominati per coerenza o chiarezza in Godot 4.0. Lo strumento di aggiornamento di progetto li rinomina automaticamente negli script.

Una serie di cambiamenti notevoli riguarda i nodi 3D, a cui è stato aggiunto il suffisso 3D per coerenza con le controparti 2D. Ad esempio, Area ora è Area3D.

Per facilitare la ricerca, questa tabella elenca tutti i nodi e le risorse che sono stati rinominati e convertiti automaticamente, escludendo quelli a cui è stato solo aggiunto il suffisso 3D al nome vecchio:

Nome vecchio (Godot 3.x)	Nome nuovo (Godot 4)
AnimatedSprite	AnimatedSprite2D
ARVRCamera	XRCamera3D
ARVRController	XRController3D
ARVRAnchor	XRAnchor3D
ARVRInterface	XRInterface
ARVROrigin	XROrigin3D
ARVRPositionalTracker	XRPositionalTracker
ARVRServer	XRServer
BoxShape	BoxShape3D
CapsuleShape	CapsuleShape3D
CubeMesh	BoxMesh
EditorSpatialGizmo	EditorNode3DGizmo
EditorSpatialGizmoPlugin	EditorNode3DGizmoPlugin
GIProbe	VoxelGI
GIProbeData	VoxelGIData
GradientTexture	GradientTexture1D
KinematicBody	CharacterBody3D
KinematicBody2D	CharacterBody2D
Light2D	PointLight2D
LineShape2D	WorldBoundaryShape2D
Ascoltatore	AudioListener3D
NavigationMeshInstance	NavigationRegion3D
NavigationPolygonInstance	NavigationRegion2D
Navigation2DServer	NavigationServer2D
PanoramaSky	Sky
Particelle	GPUParticles3D
Particles2D	GPUParticles2D
ParticlesMaterial	ParticleProcessMaterial
Physics2DDirectBodyState	PhysicsDirectBodyState2D
Physics2DDirectSpaceState	PhysicsDirectSpaceState2D
Physics2DServer	PhysicsServer2D
Physics2DShapeQueryParameters	PhysicsShapeQueryParameters2D
Physics2DTestMotionResult	PhysicsTestMotionResult2D
PlaneShape	WorldBoundaryShape3D
Position2D	Marker2D
Position3D	Marker3D
ProceduralSky	Sky
RayShape	SeparationRayShape3D
RayShape2D	SeparationRayShape2D
ShortCut	Shortcut
Spatial	Node3D
SpatialGizmo	Node3DGizmo
SpatialMaterial	StandardMaterial3D
Sprite	Sprite2D
StreamTexture	CompressedTexture2D
TextureProgress	TextureProgressBar
VideoPlayer	VideoStreamPlayer
ViewportContainer	SubViewportContainer
Viewport	SubViewport
VisibilityEnabler	VisibleOnScreenEnabler3D
VisibilityNotifier	VisibleOnScreenNotifier3D
VisibilityNotifier2D	VisibleOnScreenNotifier2D
VisibilityNotifier3D	VisibleOnScreenNotifier3D
VisualServer	RenderingServer
VisualShaderNodeScalarConstant	VisualShaderNodeFloatConstant
VisualShaderNodeScalarFunc	VisualShaderNodeFloatFunc
VisualShaderNodeScalarOp	VisualShaderNodeFloatOp
VisualShaderNodeScalarClamp	VisualShaderNodeClamp
VisualShaderNodeVectorClamp	VisualShaderNodeClamp
VisualShaderNodeScalarInterp	VisualShaderNodeMix
VisualShaderNodeVectorInterp	VisualShaderNodeMix
VisualShaderNodeVectorScalarMix	VisualShaderNodeMix
VisualShaderNodeScalarSmoothStep	VisualShaderNodeSmoothStep
VisualShaderNodeVectorSmoothStep	VisualShaderNodeSmoothStep
VisualShaderNodeVectorScalarSmoothStep	VisualShaderNodeSmoothStep
VisualShaderNodeVectorScalarStep	VisualShaderNodeStep
VisualShaderNodeScalarSwitch	VisualShaderNodeSwitch
VisualShaderNodeScalarTransformMult	VisualShaderNodeTransformOp
VisualShaderNodeScalarDerivativeFunc	VisualShaderNodeDerivativeFunc
VisualShaderNodeVectorDerivativeFunc	VisualShaderNodeDerivativeFunc
VisualShaderNodeBooleanUniform	VisualShaderNodeBooleanParameter
VisualShaderNodeColorUniform	VisualShaderNodeColorParameter
VisualShaderNodeScalarUniform	VisualShaderNodeFloatParameter
VisualShaderNodeCubeMapUniform	VisualShaderNodeCubeMapParameter
VisualShaderNodeTextureUniform	VisualShaderNodeTexture2DParameter
VisualShaderNodeTextureUniformTriplanar	VisualShaderNodeTextureParameterTriplanar
VisualShaderNodeTransformUniform	VisualShaderNodeTransformParameter
VisualShaderNodeVec3Uniform	VisualShaderNodeVec3Parameter
VisualShaderNodeUniform	VisualShaderNodeParameter
VisualShaderNodeUniformRef	VisualShaderNodeParameterRef

Rinomina manuale di metodi, proprietà, segnali e costanti

A causa di come funziona lo strumento di aggiornamento dei progetti, non tutte i cambi di nome delle API si possono effettuare automaticamente. L'elenco seguente contiene tutti i nomi che bisogna cambiare manualmente attraverso l'editor di script.

Se non si riesce a trovare un nodo o una risorsa nell'elenco sottostante, fare riferimento alla tabella sopra per trovarne il nuovo nome.

Suggerimento

Si può usare la finestra di dialogo Sostituisci nei file per velocizzare la sostituzione premendo Ctrl + Shift + R mentre l'editor di script è aperto. Tuttavia, attenzione perché la finestra di dialogo "Sostituisci nei file" non offre alcun modo per annullare una sostituzione. Usa il controllo versioni per effettuare regolarmente un commit del proprio lavoro di aggiornamento. Si possono anche usare strumenti da riga di comando come sd se è necessario qualcosa di più flessibile della finestra di dialogo "Sostituisci nei file" nell'editor.

Se si utilizza C#, ricordarsi di cercare l'utilizzo obsoleto dell'API con la notazione PascalCase nel progetto (ed eseguire la sostituzione con la notazione PascalCase).

Metodi

Le classi File e Directory sono state sostituite da FileAccess e DirAccess, che hanno un'API completamente diversa. Molti metodi sono ora statici, il che significa che è possibile chiamarli direttamente su FileAccess o DirAccess senza dover creare un'istanza di quella classe.
I metodi relativi a schermi e finestre del singleton OS (come OS.get_screen_size()) sono stati spostati nel singleton DisplayServer. Anche la denominazione dei metodi è cambiata, utilizzando invece la forma DisplayServer.<object>_<get/set>_property(). Ad esempio, OS.get_screen_size() diventa DisplayServer.screen_get_size().
I metodi di data e ora del singleton OS sono stati spostati nel singleton Time. (Il singleton Time è disponibile anche in Godot 3.5 e versioni successive.)
Potrebbe essere necessario sostituire alcune chiamate di instance() con instantiate(). Il convertitore dovrebbe gestirlo automaticamente, ma questo si basa su codice personalizzato che potrebbe non funzionare nel 100% delle situazioni.
AcceptDialog set_autowrap() è ora set_autowrap_mode().
AnimationNode process() è ora _process() (notare il trattino basso iniziale, che indica un metodo virtuale).
AnimationPlayer add_animation() è ora add_animation_library() e utilizza un'AnimationLibrary.
AnimationTree set_process_mode() è ora set_process_callback().
Array empty() è ora is_empty().
Array invert() è ora reverse().
Array remove() è ora remove_at().
AStar2D e AStar3D get_points() è ora get_points_id().
BaseButton set_event() è ora set_shortcut().
Camera2D get_h_offset() è ora get_drag_horizontal_offset().
Camera2D get_v_offset() è ora get_drag_vertical_offset().
Camera2D set_h_offset() è ora set_drag_horizontal_offset().
Camera2D set_v_offset() è ora set_drag_vertical_offset().
CanvasItem raise() è ora move_to_front().
CanvasItem update() è ora queue_redraw().
Control get_stylebox() è ora get_theme_stylebox().
Control set_tooltip() è ora set_tooltip_text().
EditorNode3DGizmoPlugin create_gizmo() è ora _create_gizmo() (notare il trattino basso iniziale, che indica un metodo virtuale).
ENetMultiplayerPeer get_peer_port() è ora get_peer().
FileDialog get_mode() è ora get_file_mode().
FileDialog set_mode() è ora set_file_mode().
GraphNode get_offset() è ora get_position_offset().
GridMap map_to_world() è ora map_to_local().
GridMap world_to_map() è ora local_to_map().
Image get_rect() è ora get_region().
ImmediateGeometry set_normal() è ora surface_set_normal().
ImmediateMesh set_color() è ora surface_set_color().
ImmediateMesh set_uv() è ora surface_set_uv().
ItemList get_v_scroll() è ora get_v_scroll_bar().
MultiPlayerAPI get_network_connected_peers() è ora get_peers().
MultiPlayerAPI get_network_peer() è ora get_peer().
MultiPlayerAPI get_network_unique_id() è ora get_unique_id().
MultiPlayerAPI has_network_peer() è ora has_multiplayer_peer().
MultiplayerAPI is_refusing_new_network_connections() è ora is_refusing_new_connections().
PacketPeerUDP is_listening() è ora is_bound().
PacketPeerUDP listen() è ora bind().
ParticleProcessMaterial set_flag() è ora set_particle_flag().
PhysicsTestMotionResult2D get_motion() è ora get_travel().
RenderingServer get_render_info() è ora get_rendering_info().
ResourceFormatLoader get_dependencies() è ora _get_dependencies() (notare il trattino basso iniziale, che indica un metodo virtuale).
ResourceFormatLoader load() è ora _load().
SceneTree change_scene() è ora change_scene_to_file().
Shortcut is_valid() è ora has_valid_event().
TileMap map_to_world() è ora map_to_local().
TileMap world_to_map() è ora local_to_map().
xform() di Transform2D è mat * vec e xform_inv() è vec * mat.
XRPositionalTracker get_name() è ora get_tracker_name().
XRPositionalTracker get_type() è ora get_tracker_type().
XRPositionalTracker _set_name() è ora get_tracker_name().

Proprietà

Nota

Se una proprietà è elencata qui, anche i metodi getter e setter associati devono essere rinominati manualmente se utilizzati nel progetto. Ad esempio, set_offset() e get_offset() di PathFollow2D e PathFollow3D devono essere rinominati rispettivamente in set_progress() e get_progress().

AudioServer device è ora output_device.
BaseButton group è ora button_group.
Camera3D zfar è ora far.
Camera3D znear è ora near
Control margin è ora offset.
InputEventMouseButton doubleclick è ora double_click.
InputEventWithModifiers alt è ora alt_pressed.
InputEventWithModifiers command è ora command_pressed.
InputEventWithModifiers control è ora ctrl_pressed.
InputEventWithModifiers meta è ora meta_pressed.
InputEventWithModifiers shift è ora shift_pressed.
Label percent_visible è ora visible_ratio.
MultiPlayerAPI refuse_new_network_connections è ora refuse_new_connections.
Node filename è ora scene_file_path.
PathFollow2D rotate è ora rotates.
PathFollow2D e PathFollow3D offset è ora progress.
RectangleShape2D extents è ora size
TextureProgressBar percent_visible è ora show_percentage.
Theme off è ora unchecked.
Theme ofs è ora offset.
Theme on è ora checked.
Window window_title è ora title.
WorldMarginShape2D d è ora distance.
La proprietà extents sui nodi CSG e VoxelGI dovrà essere sostituita con size, con il valore impostato dimezzato (poiché non sono più mezze-estensioni). Ciò influisce anche sui metodi setter/getter set_extents() e get_extents().
La proprietà Engine.editor_hint è stata rimossa a favore del metodo Engine.is_editor_hint(). Questo perché è di sola lettura e le proprietà in Godot non si utilizzano per valori di sola lettura.

Enumerazioni

CPUParticles2D FLAG_MAX è ora PARTICLE_FLAG_MAX.

Segnali

FileSystemDock instantiate è ora instance.
CanvasItem hide è ora hidden. Questo cambio del nome non si applica al metodo hide(), ma solo al segnale.
Tween tween_all_completed è ora loop_finished.
EditorSettings changed è ora settings_changed.

Costanti

I nomi dei colori ora sono in maiuscolo e utilizzano il trattino basso tra le parole. Ad esempio, Color.pallidoverde ora diventa Color.PALE_GREEN.
Le costanti NOTIFICATION_ di MainLoop sono state duplicate in Node, il che significa che è possibile rimuovere il prefisso MainLoop. quando si fa riferimento a esse.
MainLoop NOTIFICATION_WM_QUIT_REQUEST è ora NOTIFICATION_WM_CLOSE_REQUEST.

Verificare le impostazioni del progetto

Diverse impostazioni del progetto sono state rinominate e alcune di esse hanno subito cambiamenti alle loro enumerazioni in modi incompatibili (ad esempio, la qualità di filtro delle ombre). Ciò significa che potrebbe essere necessario reimpostare alcuni valori delle impostazioni del progetto. Assicurarsi che l'opzione Avanzate sia abilitata nella finestra di dialogo delle impostazioni del progetto, in modo da poter vedere tutte le impostazioni.

Verificare le impostazioni di ambiente

Le impostazioni relative alla qualità grafica sono state spostate dalle proprietà di Environment alle impostazioni del progetto. Questo per facilitare aggiustamenti alla qualità in fase di esecuzione, senza dover accedere alla risorsa Environment attualmente attiva e modificarne le proprietà.

Di conseguenza, sarà necessario configurare le impostazioni di qualità dell'ambiente nelle impostazioni del progetto, poiché le vecchie impostazioni di qualità dell'ambiente non vengono convertite automaticamente in impostazioni del progetto.

Se si dispone di un menu di impostazioni grafiche che ha cambiato le proprietà dell'ambiente in Godot 3.x, sarà necessario modificarne il codice per richiamare i metodi del RenderingServer che influenzano la qualità degli effetti ambientali. Solo l'"interruttore base" di ciascun effetto ambientale e le relative manopole visive rimangono all'interno della risorsa Environment.

Aggiornare gli shader

Sono stati apportati alcuni cambiamenti agli shader che non sono coperte dallo strumento di aggiornamento. Sarà necessario apportare alcune modifiche manualmente, soprattutto se lo shader utilizza trasformazioni dello spazio di coordinate o una funzione light() personalizzata.

L'estensione di file .shader non è più supportata, il che significa che è necessario rinominare i file .shader in .gdshader e aggiornare di conseguenza i riferimenti nei file di scene/risorse, attraverso un editor di testo esterno.

Ci sono alcune modifiche importanti che sarà necessario apportare agli shader:

Le modalità di filtraggio e di ripetizione delle texture sono ora impostati sulle singole uniformi, anziché sui file di texture stessi.
hint_albedo è ora source_color.
hint_color è ora source_color.
Le variabili di matrice integrate sono state rinominate.
Gli shader di particelle non utilizzano più la funzione di elaborazione vertex(). Invece, utilizzano start() e process().
Nei renderer Forward+ e Mobile, le coordinate normalizzate del dispositivo ora hanno un intervallo Z di [0.0,1.0] invece di [-1.0,1.0]. Quando si ricostruisce l'NDC da SCREEN_UV e profondità, utilizzare vec3 ndc = vec3(SCREEN_UV * 2.0 - 1.0, profondità); invece di vec3 ndc = vec3(SCREEN_UV, profondità) * 2.0 - 1.0;. Il renderer Compatibilità rimane invariato, utilizzando lo stesso intervallo Z NDC della versione 3.x.
Il modello di illuminazione è cambiato. Se uno shader ha una funzione light() personalizzata, potrebbe essere necessario apportare modifiche per ottenere lo stesso risultato visivo.
Dalla versione 4.3 in poi, è stata implementata la tecnica del buffer di profondità Z inverso, il che potrebbe danneggiare gli shader avanzati. Consultare Introducing Reverse Z (AKA I'm sorry for breaking your shader).

Consulta Linguaggio di shading per ulteriori informazioni.

Questo elenco non è esaustivo. Se hai apportato tutte le modifiche menzionate qui e il tuo shader continua a non funzionare, prova a chiedere aiuto in uno dei canali della comunità.

Aggiornare gli script per tenere conto dei cambiamenti non compatibili

Alcune modifiche apportate tra Godot 3.x e 4 non sono cambi di nomi, ma interrompono comunque la compatibilità con le versioni precedenti a causa del comportamento predefinito diverso.

Gli esempi più notevoli di questo sono:

Le funzioni di ciclo di vita come _ready() e _process() non chiamano più implicitamente le funzioni delle classi padre con lo stesso nome. È invece necessario utilizzare super() all'inizio di una tale funzione nella classe figlia, in modo che la funzione della classe padre venga chiamata per prima.
Sia String sia StringName sono ora esposti a GDScript. Ciò consente maggiori ottimizzazioni, poiché StringName è specificamente progettato per stringhe "costanti" create una sola volta e riutilizzate più volte. Questi tipi non sono strettamente equivalenti tra loro, il che significa che is_same("example", &"example") restituisce false. Sebbene nella maggior parte dei casi siano intercambiabili ("example" == &"example" restituisce true), a volte potrebbe essere necessario sostituire "example" con &"example".
La sintassi dei setter e getter in GDScript è stata modificata, ma viene convertita solo parzialmente dallo strumento di conversione. Nella maggior parte dei casi, sono necessarie modifiche manuali per ripristinare il funzionamento dei setter e getter.
La sintassi di connessione dei segnali in GDScript è stata modificata. Lo strumento di conversione utilizzerà la sintassi basata su stringhe, ancora presente in Godot 4, ma si consiglia di passare alla sintassi basata su Signal descritta nella suddetta pagina. Facendo così, le stringhe non sono più coinvolte, evitando errori nei nomi dei segnali che si possono rilevare solo in fase di esecuzione.
Gli script integrati che sono script di strumento non ricevono la parola chiave tool convertita nell'annotazione @tool.
Il nodo Tween è stato rimosso a favore dei Tweener, disponibili anche in Godot 3.5 e versioni successive. Per maggiori dettagli, consultare la pull request originale.
randomize() viene ora chiamato automaticamente al caricamento del progetto, quindi per una casualità deterministica con l'istanza globale di RandomNumberGenerate è necessario impostare manualmente un seed nella funzione _ready() di uno script.
call_group(), set_group() e notify_group() sono ora immediati normalmente. Se si richiama una funzione costosa, ciò potrebbe causare problemi di stuttering se utilizzato su un gruppo contenente un numero elevato di nodi. Per utilizzare le chiamate differite come in precedenza, sostituire call_group(...) con call_group_flags(SceneTree.GROUP_CALL_DEFERRED, ...) (e fare lo stesso con set_group() e notify_group() rispettivamente).
Invece di rotation_degrees, la proprietà rotation è esposta nell'editor, la quale è visualizzata automaticamente in gradi nel pannello dell'Ispettore. Questo potrebbe causare danneggiare le animazioni, poiché la conversione non viene gestita automaticamente dallo strumento di conversione.
AABB la funzione has_no_surface() è stata invertita e rinominata in has_surface().
AABB e Rect2 la funzione has_no_area() è stata invertita e rinominata in has_area().
AnimatedTexture la proprietà fps è stata sostituita da speed_scale, che funziona allo stesso modo della proprietà playback_speed di AnimationPlayer.
AnimatedSprite2D e AnimatedSprite3D ora consentono valori negativi di speed_scale. Ciò potrebbe causare problemi di animazione se si è fatto affidamento sul fatto che speed_scale fosse limitato internamente a 0.0.
AnimatedSprite2D e AnimatedSprite3D la proprietà playing è stata rimossa. Utilizzare il metodo play()/stop() OPPURE configurare l'animazione autoplay tramite il pannello inferiore di SpriteFrames (ma non entrambi alla volta).
Il secondo parametro di slice() in Array (end) è ora esclusivo, anziché inclusivo. Ad esempio, ciò significa che [1, 2, 3].slice(0, 1) ora restituisce [1] invece di [1, 2].
I segnali di BaseButton sono ora button_up e button_down. La proprietà pressed è ora button_pressed.
Camera2D la proprietà rotating è stata sostituita da ignore_rotation, che ha un comportamento invertito.
La proprietà zoom di Camera2D è stata invertita: i valori più alti ora ingrandiscono, anziché rimpicciolire.
Node il metodo remove_and_skip() è stato rimosso. Se è necessario ri-implementarlo in uno script, è possibile usare la vecchia implementazione in C++ come riferimento.
OS.get_system_time_secs() dovrebbe essere convertito in Time.get_time_dict_from_system()["second"].
Il metodo save() di ResourceSaver ora ha gli argomenti invertiti (resource: Resource, path: String). Questo vale anche per il metodo _save() di ResourceFormatSaver.
Un StreamPeerTCP deve avere poll() chiamato su di esso per aggiornare il suo stato, invece di affidarsi al polling automatico di get_status(): GH-59582
String il metodo right() di ha cambiato comportamento: ora restituisce un numero di caratteri a partire dalla parte destra della stringa, anziché dalla parte destra della stringa da una posizione specificata. Se è necessario il vecchio comportamento, è possibile usare substr().
is_connected_to_host() è stato rimosso da StreamPeerTCP e PacketPeerUDP come da GH-59582. get_status() può essere utilizzato al suo posto in StreamPeerTCP. is_socket_connected() può essere utilizzato in PacketPeerUDP.
In _get_property_list(), la stringa indicativa di proprietà or_lesser è ora or_less.
In _get_property_list(), la stringa indicativa di proprietà noslider è ora no_slider.
VisualShaderNodeVec4Parameter ora accetta come parametro Vector4 invece di Quaternion.

Nodi/risorse rimossi o rimpiazzati

Di seguito sono elencati tutti i nodi che sono stati sostituiti da altri nodi che richiedono una configurazione diversa. La configurazione deve essere rifatta da zero, poiché il convertitore di progetto non è in grado di aggiornare le configurazioni esistenti:

Nodo rimosso	Approssimazione più vicina	Commento
AnimationTreePlayer	AnimationTree	AnimationTreePlayer è stato deprecato da Godot 3.1.
BakedLightmap	LightmapGI	Vedi Using Lightmap global illumination.
BakedLightmapData	LightmapGIData	Vedi Using Lightmap global illumination.
BitmapFont	FontFile	Vedi Utilizzare i font.
DynamicFont	FontFile
DynamicFontData	FontFile
ClippedCamera	Camera2D o Camera3D	La forma piramidale della telecamera è stata spostata in :ref:'class_Camera3D'.
InterpolatedCamera	Camera2D o Camera3D
Navigation2D	Node2D	Sostituito da altri nodi di navigazione 2D.
Navigation3D	Node3D	Sostituito da altri nodi di navigazione 3D.
OpenSimplexNoise	FastNoiseLite	Ha parametri diversi e più tipi di noise, come quello cellulare. Non supporta il noise 4D, in quanto assente nella libreria FastNoiseLite.
ToolButton	Button	ToolButton era un pulsante con la proprietà Flat abilitata per impostazione predefinita.
YSort	Node2D o Control	CanvasItem ha una nuova proprietà Ordinamento in Y abilitato in 4.0.
ProximityGroup	Node3D	VisibleOnScreenNotifier3D può fungere da sostituto.
Portal	Node3D	L'occlusion culling tramite portali e stanze è stato sostituito dall'occlusion culling raster (nodo OccluderInstance3D), che richiede un processo di configurazione diverso.
Room	Node3D
RoomManager	Node3D
RoomGroup	Node3D
Occluder	Node3D	L'occlusion culling di geometria è stato sostituito dall'occlusion culling raster (nodo OccluderInstance3D), che richiede un processo di configurazione diverso.
OccluderShapeSphere	Resource

Se si carica un vecchio progetto, il nodo verrà sostituito automaticamente con la sua approssimazione più vicina (anche se non si utilizza lo strumento di aggiornamento di progetti).

Cambiamenti al threading

Le API di threading sono cambiate nella versione 4.0. Ad esempio, il seguente frammento di codice in Godot 3.x deve essere modificato per funzionare in 4.0:

# 3.x
var start_success = new_thread.start(self, "__threaded_background_loader",
    [resource_path, thread_num]
)

# 4.0
var start_success = new_thread.start(__threaded_background_loader.bind(resource_path, thread_num))

Thread.is_active() non è più utilizzato e si dovrebbe convertire in Thread.is_alive().

Vedi anche

Consulta il changelog per una lista completa di cambiamenti tra Godot 3.x e 4.

Interruzione di compatibilità delle risorse ArrayMesh

Se una risorsa ArrayMesh è stata salvata in un file .res o .tres, il formato utilizzato nella versione 4.0 non è compatibile con quello della versione 3.x. Sarà necessario ripetere la procedura di importazione del file mesh sorgente e salvarlo nuovamente come risorsa ArrayMesh.

Elenco di metodi, proprietà, segnali e costanti rinominati automaticamente

The editor/project_upgrade/renames_map_3_to_4.cpp source file lists all automatic renames performed by the project upgrade tool. Lines that are commented out refer to API renames that cannot be performed automatically.

Trasferire le impostazioni dell'editor

Godot 3.x e 4.0 utilizzano file di impostazioni dell'editor diversi. Ciò significa che le loro impostazioni si possono modificare indipendentemente l'una dall'altra.

Se desideri trasferire le impostazioni di Godot 3.x a Godot 4, apri la cartella delle impostazioni dell'editor e copia editor_settings-3.tres in editor_settings-4.tres mentre l'editor di Godot 4 è chiuso.

Nota

I nomi e le categorie di molte impostazioni sono cambiati da Godot 3.x. Le impostazioni dell'editor il cui nome o la cui categoria sono cambiati non verranno trasferite a Godot 4.0; sarà necessario impostarne nuovamente i valori.

Aggiornare le impostazioni di controllo versione

Godot 3.x e 4.x hanno liste completamente diverse di file e cartelle da ignorare dal proprio sistema di controllo versione.