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

Upgrading from Godot 4.6 to Godot 4.7

For most games and apps made with 4.6 it should be relatively safe to migrate to 4.7. This page intends to cover everything you need to pay attention to when migrating your project.

做出更改

If you are migrating from 4.6 to 4.7, the breaking changes listed here might affect you. Changes are grouped by areas/systems.

這篇文章指出了每項破壞性改動是否會影響 GDScript，以及 C# 的破壞性改動是 二進位相容 還是 原始程式碼相容：

• 二進制相容 - 現有的二進制檔案無需重新編譯即可成功載入和執行，且運行時的行為不會改變。

• ** 原始程式碼相容** —— 在升級 Godot 時，原始程式碼可成功編譯，無需更改。

核心

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
Object
Method is_class changes class parameter type from String to StringName	✔️	✔️	✔️	GH-118582
ZIPPacker
Method start_file adds new permissions and modified_time optional parameters	✔️	✔️	✔️	GH-115946
OptimizedTranslation
Method generate changes return type from void to bool	✔️	❌	✔️	GH-119563

2D

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
CPUParticles2D
Method request_particles_process adds new process_time_residual optional parameter	✔️	✔️	✔️	GH-109142
GPUParticles2D
Method request_particles_process adds new process_time_residual optional parameter	✔️	✔️	✔️	GH-109142

3D

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
CPUParticles3D
Method request_particles_process adds new process_time_residual optional parameter	✔️	✔️	✔️	GH-109142
GPUParticles3D
Method request_particles_process adds new process_time_residual optional parameter	✔️	✔️	✔️	GH-109142

建立節點

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
Control
Property accessibility_live changes type from DisplayServer.AccessibilityLiveMode to AccessibilityServer.AccessibilityLiveMode	✔️	❌	❌	GH-116839
RichTextLabel
Enum field ImageUpdateMask.UPDATE_WIDTH_IN_PERCENT renamed to ImageUpdateMask.UPDATE_WIDTH_UNIT	❌	✔️	❌	GH-112617
Method add_image changes width parameter type from int to float	✔️	✔️	✔️	GH-112617
Method add_image changes height parameter type from int to float	✔️	✔️	✔️	GH-112617
Method add_image renames width_in_percent parameter to width_unit and changes type from bool to RichTextLabel.ImageUnit	✔️	✔️	❌	GH-112617
Method add_image renames height_in_percent parameter to height_unit and changes type from bool to RichTextLabel.ImageUnit	✔️	✔️	❌	GH-112617
Method update_image changes width parameter type from int to float	✔️	✔️	✔️	GH-112617
Method update_image changes height parameter type from int to float	✔️	✔️	✔️	GH-112617
Method update_image renames width_in_percent parameter to width_unit and changes type from bool to RichTextLabel.ImageUnit	✔️	✔️	❌	GH-112617
Method update_image renames height_in_percent parameter to height_unit and changes type from bool to RichTextLabel.ImageUnit	✔️	✔️	❌	GH-112617

文字

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
字型
Method find_variation adds new palette_index and custom_colors optional parameters	✔️	✔️	✔️	GH-117149
TreeItem
Method select adds new set_as_cursor optional parameter	✔️	✔️	✔️	GH-119367

算繪

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
Image
Method save_exr adds new color_image and max_linear_value optional parameters	✔️	✔️	✔️	GH-117800
Method save_exr_to_buffer adds new color_image and max_linear_value optional parameters	✔️	✔️	✔️	GH-117800
ImageTexture
Method get_format moved to base class Texture2D	✔️	✔️	✔️	GH-109004
PortableCompressedTexture2D
Method get_format moved to base class Texture2D	✔️	✔️	✔️	GH-109004
RenderingServer
Method particles_request_process_time renames time parameter to process_time and adds new process_time_residual optional parameter	✔️	✔️	❌	GH-109142
Method viewport_set_size adds new view_count optional parameter	✔️	✔️	✔️	GH-115799

動畫

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
動畫
Property length changes type metadata from float to double	✔️	❌	❌	GH-116394
AnimationNodeBlendSpace1D
Method add_blend_point adds new name optional parameter	✔️	✔️	✔️	GH-110369
AnimationNodeBlendSpace2D
Method add_blend_point adds new name optional parameter	✔️	✔️	✔️	GH-110369

物理

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
PhysicsServer2D
Method body_set_shape_as_one_way_collision adds new direction optional parameter	✔️	✔️	✔️	GH-104736
PhysicsServer2DExtension
Method _body_set_shape_as_one_way_collision adds new direction parameter	❌	❌	❌	GH-104736

音訊

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
AudioEffectSpectrumAnalyzer
Property tap_back_pos removed	❌	❌	❌	GH-114355

XR

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
OpenXRExtensionWrapper
Method _on_register_metadata adds new interaction_profile_metadata parameter	❌	❌	❌	GH-117399
OpenXRSpatialAnchorCapability
Method create_new_anchor adds new next optional parameter	✔️	✔️	✔️	GH-118128

編輯器

改動	GDScript 格式化字串	C# 二進位相容	C# 原始程式碼相容	簡介
EditorSceneFormatImporter
Constant IMPORT_ANIMATION moved to enum ImportFlags	✔️	✔️	❌	GH-115788
Constant IMPORT_DISCARD_MESHES_AND_MATERIALS moved to enum ImportFlags	✔️	✔️	❌	GH-115788
Constant IMPORT_FAIL_ON_MISSING_DEPENDENCIES moved to enum ImportFlags	✔️	✔️	❌	GH-115788
Constant IMPORT_FORCE_DISABLE_MESH_COMPRESSION moved to enum ImportFlags	✔️	✔️	❌	GH-115788
Constant IMPORT_GENERATE_TANGENT_ARRAYS moved to enum ImportFlags	✔️	✔️	❌	GH-115788
Constant IMPORT_SCENE moved to enum ImportFlags	✔️	✔️	❌	GH-115788
Constant IMPORT_USE_NAMED_SKIN_BINDS moved to enum ImportFlags	✔️	✔️	❌	GH-115788
EditorVCSInterface
Method _commit adds new amend parameter	❌	❌	❌	GH-117968

做出更改

動畫

備註

AnimationNodeBlendSpace1D and AnimationNodeBlendSpace2D have a new SyncMode enum that replaces the previous boolean sync property. If you are using an AnimationTree and your animations aren't transitioning correctly after upgrading, you may need to set that value in each of your blend spaces to get the desired behavior back.

The new sync modes are documented in AnimationNodeBlendSpace1D.sync_mode and AnimationNodeBlendSpace2D.sync_mode.

算繪

備註

The LinearToSRGB visual shader no longer clamps to the range [0.0, 1.0] when using the Mobile or Forward+ renderer (GH-113956).

備註

CanvasItem now avoids adding the antialiasing feather when drawing lines (GH-105122). The feather made lines appear thicker than intended, projects that relied on this behavior will have to be updated to draw a thicker line width.

物理

備註

The default area_mask for AudioStreamPlayer was changed from 1 to 0 (disabled) (GH-107679). If you use the audio_bus_override feature on Area2D or Area3D, and you use the AudioStreamPlayer default area_mask (just layer 1 ticked), you will need to reset the mask to layer 1 — otherwise, the bus overrides will stop working. If the mask was set to anything except layer 1, it will continue to work as expected.

備註

When using Jolt Physics as the 3D physics engine, WorldBoundaryShape3D will now use the same convention as Godot when applying WorldBoundaryShape3D.plane.d, resulting in the sign of the plane distance being interpreted in the opposite way compared to Godot 4.6 (GH-118948). You will need to flip the sign yourself to get the same behavior as in Godot 4.6.

備註

When using Jolt Physics as the 3D physics engine, SoftBody3D will no longer default its mass to 0, which resulted in an automatically calculated weight of 1 kg per point, resulting in a very high total mass for the body. Now instead it will default to 1 kg for the entire SoftBody3D, same as Godot Physics (GH-116041).

備註

When using Jolt Physics as the 3D physics engine, SoftBody3D will now apply SoftBody3D.linear_stiffness in a way that better matches Godot Physics, and in a way that's more appropriate in general (GH-116041). This will affect every SoftBody3D instance in one way or another, meaning you will need to re-tweak properties like SoftBody3D.linear_stiffness and SoftBody3D.damping_coefficient to achieve your desired behavior.

備註

When using Jolt Physics as the 3D physics engine, Area3D will now report overlaps with SoftBody3D from its various signals and methods (GH-114198). To work around this breaking change, configure your collision layers/masks such that any undesirable interactions between Area3D and SoftBody3D are ignored.

輸入

備註

The device IDs for mouse and keyboard were changed from 0 to InputEvent.DEVICE_ID_MOUSE and InputEvent.DEVICE_ID_KEYBOARD because some joypads may use 0 as their ID (GH-116274). Check the input event by type or compare the device ID InputEvent.device to the constants InputEvent.DEVICE_ID_MOUSE and InputEvent.DEVICE_ID_KEYBOARD instead.

GDScript

備註

Setting the element of packed arrays no longer calls the setter for the entire packed array property (GH-113228).

備註

Methods that inherit from a method with a typed return now inherit the return type as well, requiring an explicit return statement in the override (GH-115763). Add return null to the end of the method to fix the error.

支援平台

備註

The minimum macOS version required to run Godot was increased from macOS 10.13 (High Sierra) to macOS 11 (Big Sur).

Changed defaults

The following default values have been changed. If your project uses any of these properties with their default value, you can achieve a similar behavior to the previous version by manually setting the values to match the old defaults.

備註

The default stretch mode and stretch aspect for newly created projects is now canvas_items and expand respectively (previously disabled and keep). This can be changed in the Project Settings under display/window/stretch/mode and display/window/stretch/aspect.

動畫

Property/Parameter	Old Default	New Default
LookAtModifier3D
Property relative	true	false

核心

Property/Parameter	Old Default	New Default
ProjectSettings
Property rendering/reflections/sky_reflections/roughness_layers	7	8

建立節點

Property/Parameter	Old Default	New Default
RichTextLabel
Method add_image parameter width_in_percent	false	0
Method add_image parameter height_in_percent	false	0
Method update_image parameter width_in_percent	false	0
Method update_image parameter height_in_percent	false	0

匯入

Property/Parameter	Old Default	New Default
ResourceImporterDynamicFont
Property hinting	1	3