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.0 a Godot 4.1

Per la maggior parte dei giochi e delle applicazioni creati in 4.0, dovrebbe essere relativamente sicuro migrare a 4.1. 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.0 alla 4.1, le modifiche incompatibili elencate qui potrebbero interessarti. Le modifiche sono raggruppate per aree/sistemi.

Avvertimento

L'API GDExtension interrompe completamente la compatibilità con la versione 4.1, quindi non è inclusa nella tabella seguente. Consultare la sezione Aggiornamento di GDExtension per 4.1 per ulteriori informazioni.

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 necessità di ricompilazione 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
Basis
Il metodo looking_at aggiunge un nuovo parametro facoltativo use_model_front	✔️	✔️	✔️	GH-76082
Object
Il metodo get_meta_list cambia il tipo restituito da PackedStringArray a Array[StringName]	✔️	❌	❌	GH-76418
Transform3D
Il metodo looking_at aggiunge un nuovo parametro facoltativo use_model_front	✔️	✔️	✔️	GH-76082
UndoRedo
Il metodo create_action aggiunge un nuovo parametro facoltativo backward_undo_ops	✔️	✔️	✔️	GH-76688
WorkerThreadPool
Il metodo wait_for_task_completion cambia il tipo restituito da void a Error	✔️	❌	✔️	GH-77143

Animazione

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
AnimationNode
Il metodo _process aggiunge un nuovo parametro test_only	❌	❌	❌	GH-75759
Il metodo blend_input aggiunge un nuovo parametro facoltativo test_only	✔️	✔️	✔️	GH-75759
Il metodo blend_node aggiunge un nuovo parametro facoltativo test_only	✔️	✔️	✔️	GH-75759
AnimationNodeStateMachinePlayback
Il metodo get_travel_path cambia il tipo restituito da PackedStringArray a Array[StringName]	✔️	❌	❌	GH-76418

Nodi 2D

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
PathFollow2D
Proprietà lookahead rimossa	❌	❌	❌	GH-72842

Nodi 3D

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
Geometry3D
Il metodo segment_intersects_convex cambia il tipo del parametro planes da Array a Array[Plane]	✔️	✔️	❌	GH-76418
MeshInstance3D
Il metodo create_multiple_convex_collisions aggiunge un nuovo parametro facoltativo settings	✔️	✔️	✔️	GH-72152
Node3D
Il metodo look_at aggiunge un nuovo parametro facoltativo use_model_front	✔️	✔️	✔️	GH-76082
Il metodo look_at_from_position aggiunge un nuovo parametro facoltativo use_model_front	✔️	✔️	✔️	GH-76082

Nodi GUI

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
CodeEdit
Il metodo add_code_completion_option aggiunge un nuovo parametro facoltativo location	✔️	✔️	✔️	GH-75746
RichTextLabel
Il metodo push_list aggiunge un nuovo parametro facoltativo bullet	✔️	✔️	✔️	GH-75017
Il metodo push_paragraph aggiunge un nuovo parametro facoltativo justification_flags	✔️	✔️	✔️	GH-75250
Il metodo push_paragraph aggiunge un nuovo parametro facoltativo tab_stops	✔️	✔️	✔️	GH-76401
Tree
Il metodo edit_selected aggiunge un nuovo parametro facoltativo force_edit	✔️	✔️	✔️	GH-76794

Fisica

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
Area2D
La proprietà priority cambia tipo da float a int	❌	❌	❌	GH-72749
Area3D
La proprietà priority cambia tipo da float a int	❌	❌	❌	GH-72749
PhysicsDirectSpaceState2D
Il metodo collide_shape cambia il tipo restituito da Array[PackedVector2Array] a Array[Vector2]	❌	❌	❌	GH-75260
PhysicsDirectSpaceState3D
Il metodo collide_shape cambia il tipo restituito da Array[PackedVector3Array] a Array[Vector3]	❌	❌	❌	GH-75260

Renderer

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
RDShaderFile
Il metodo get_version_list cambia il tipo restituito da PackedStringArray a Array[StringName]	✔️	❌	❌	GH-76418
RenderingDevice
Il metodo draw_list_begin cambia il tipo del parametro storage_textures da Array a Array[RID]	✔️	✔️	❌	GH-76418
RenderingServer
Il metodo global_shader_parameter_get_list cambia il tipo restituito da PackedStringArray a Array[StringName]	✔️	❌	❌	GH-76418
SurfaceTool
Il metodo add_triangle_fan cambia il tipo del parametro tangents da Array a Array[Plane]	✔️	✔️	❌	GH-76418

Navigazione

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
NavigationAgent2D
Il metodo set_velocity è stato sostituito dalla proprietà velocity	✔️	❌	❌	GH-69988
La proprietà time_horizon è stata separata in time_horizon_agents e time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationAgent3D
La proprietà agent_height_offset è stata rinominata in path_height_offset	❌	❌	❌	GH-69988
Proprietà ignore_y rimossa	❌	❌	❌	GH-69988
Il metodo set_velocity è stato sostituito dalla proprietà velocity	✔️	❌	❌	GH-69988
La proprietà time_horizon è stata separata in time_horizon_agents e time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationObstacle2D
Proprietà estimate_radius rimossa	❌	❌	❌	GH-69988
Il metodo get_rid è stato rinominato in get_agent_rid	❌	❌	❌	GH-69988
NavigationObstacle3D
Proprietà estimate_radius rimossa	❌	❌	❌	GH-69988
Il metodo get_rid è stato rinominato in get_agent_rid	❌	❌	❌	GH-69988
NavigationServer2D
Il metodo agent_set_callback è stato rinominato in agent_set_avoidance_callback	❌	❌	❌	GH-69988
Metodo agent_set_target_velocity rimosso	❌	❌	❌	GH-69988
Il metodo agent_set_time_horizon è stato separato in agent_set_time_horizon_agents e agent_set_time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationServer3D
Il metodo agent_set_callback è stato rinominato in agent_set_avoidance_callback	❌	❌	❌	GH-69988
Metodo agent_set_target_velocity rimosso	❌	❌	❌	GH-69988
Il metodo agent_set_time_horizon è stato separato in agent_set_time_horizon_agents e agent_set_time_horizon_obstacles	❌	❌	❌	GH-69988

Networking

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
WebRTCPeerConnectionExtension
Il metodo _create_data_channel cambia il tipo restituito da Object a WebRTCDataChannel	✔️	❌	✔️	GH-78237

Estensioni per l'editor

Cambiamento	Compatibili con GDScript	Compatibili con eseguibili C#	Compatibili con codice sorgente C#	Introdotti
AnimationTrackEditPlugin
Tipo AnimationTrackEditPlugin rimosso	❌	❌	❌	GH-76413
EditorInterface
Il tipo EditorInterface cambia l'ereditarietà da Node a Object	✔️	❌	❌	GH-76176
Il metodo set_movie_maker_enabled è stato sostituito dalla proprietà movie_maker_enabled	✔️	❌	❌	GH-76176
Il metodo is_movie_maker_enabled è stato sostituito dalla proprietà movie_maker_enabled	✔️	❌	❌	GH-76176
EditorResourcePreviewGenerator
Il metodo _generate aggiunge un nuovo parametro metadata	❌	❌	❌	GH-64628
Il metodo _generate_from_path aggiunge un nuovo parametro metadati	❌	❌	❌	GH-64628
EditorUndoRedoManager
Il metodo create_action aggiunge un nuovo parametro facoltativo backward_undo_ops	✔️	✔️	✔️	GH-76688

Cambiamenti di comportamento

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

Cambiamento	Introdotti
SubViewportContainer
Quando gli eventi di input devono raggiungere i SubViewport e i loro figli, SubViewportContainer.mouse_filter ora deve essere MOUSE_FILTER_STOP o MOUSE_FILTER_PASS. Consultare GH-79271 per i dettagli.	GH-57894
I nodi SubViewportContainer sovrapposti, che dovrebbero tutti ricevere gli eventi di input del mouse, ora devono essere sostituiti dai nodi Area2D. Consultare GH-79128 per i dettagli.	GH-57894
Viewport
I nodi Viewport, con la selezione fisica abilitata, ora configurano automaticamente gli InputEvent come gestiti. Consultare GH-79897 per soluzioni alternative.	GH-77595

Aggiornamento di GDExtension per 4.1

Per risolvere un bug grave, in Godot 4.1 abbiamo dovuto interrompere enormemente la compatibilità binaria e marginalmente la compatibilità del codice sorgente.

Ciò significa che le GDExtension realizzate per Godot 4.0 dovranno essere ricompilate per Godot 4.1 (utilizzando il ramo 4.1 di godot-cpp), con una piccola modifica al loro codice sorgente.

In Godot 4.0, la funzione "entry_symbol" assomiglia a questa:

GDExtensionBool GDE_EXPORT example_library_init(const GDExtensionInterface *p_interface, const GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
    godot::GDExtensionBinding::InitObject init_obj(p_interface, p_library, r_initialization);

    init_obj.register_initializer(initialize_example_module);
    init_obj.register_terminator(uninitialize_example_module);
    init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);

    return init_obj.init();
}

Tuttavia, per Godot 4.1, dovrebbe apparire così:

GDExtensionBool GDE_EXPORT example_library_init(GDExtensionInterfaceGetProcAddress p_get_proc_address, const GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
    godot::GDExtensionBinding::InitObject init_obj(p_get_proc_address, p_library, r_initialization);

    init_obj.register_initializer(initialize_example_module);
    init_obj.register_terminator(uninitialize_example_module);
    init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);

    return init_obj.init();
}

Ci sono due piccoli cambiamenti:

1. Il primo argomento cambia da const GDExtensionInterface *p_interface a GDExtensionInterfaceGetProcAddress p_get_proc_address

2. Il costruttore per la variabile init_obj ora riceve p_get_proc_address come primo parametro

È necessario anche aggiungere una riga compatibility_minimum in più al file .gdextension, in modo da apparire così:

[configuration]

entry_symbol = "example_library_init"
compatibility_minimum = 4.1

Ciò permette a Godot di sapere che la GDExtension è stata aggiornata e si può caricare in modo sicuro in Godot 4.1.