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# 소스 호환	소개
오브젝트
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# 소스 호환	소개
GPUParticles2D
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# 소스 호환	소개
GPUParticles3D
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
Server
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# 소스 호환	소개
Expression Node(표현식 노드)
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# 소스 호환	소개
Godot 인터페이스
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).

변경된 기본값

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.

애니메이션

매개변수	Old Default	New Default
LookAtModifier3D
Property relative	'값'	false

코어

매개변수	Old Default	New Default
프로젝트 설정
속성 rendering/reflections/sky_reflections/roughness_layers	7	8

노드 만들기

매개변수	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

가져오기

매개변수	Old Default	New Default
ResourceImporterDynamicFont
Property hinting	1	3