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

Godot 4.5에서 Godot 4.6으로 업그레이드

4.5로 제작된 대부분의 게임과 앱의 경우 4.6으로 마이그레이션하는 것이 상대적으로 안전합니다. 이 페이지에서는 프로젝트를 마이그레이션할 때 주의해야 할 모든 것을 다루려고 합니다.

깨는 변경사항

4.5에서 4.6으로 마이그레이션하는 경우 여기에 나열된 주요 변경 사항이 영향을 미칠 수 있습니다. 변경 사항은 영역/시스템별로 그룹화됩니다.

이 문서에서는 각 주요 변경 사항이 GDScript에 영향을 미치는지 여부와 C# 주요 변경 사항이 바이너리 호환 또는 *소스 호환*인지 여부를 나타냅니다.

• 바이너리 호환 가능 - 기존 바이너리는 재컴파일 없이 성공적으로 로드 및 실행되며 런타임 동작은 변경되지 않습니다.

• 소스 호환 가능 - 소스 코드는 Godot를 업그레이드할 때 변경 없이 성공적으로 컴파일됩니다.

코어

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
파일 액세스
메소드 create_temp``는 ``mode_flags 매개변수 유형을 ``int``에서 ``FileAccess.ModeFlags``로 변경합니다.	✔️	|✔️ 호환 가능|	|✔️ 호환 가능|	GH-114053
get_as_text 메소드는 skip_cr 매개변수를 제거합니다.	✔️	|✔️ 호환 가능|	|✔️ 호환 가능|	GH-110867
성능
add_custom_monitor 메소드는 새로운 type 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	|✔️ 호환 가능|	GH-110433

애니메이션

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
AnimationPlayer
assigned_animation 속성은 유형을 ``String``에서 ``StringName``로 변경합니다.	✔️	❌	❌	GH-110767
autoplay 속성은 유형을 ``String``에서 ``StringName``로 변경합니다.	✔️	❌	❌	GH-110767
current_animation 속성은 유형을 ``String``에서 ``StringName``로 변경합니다.	✔️	❌	❌	GH-110767
메서드 ``get_queue``는 반환 유형을 ``PackedStringArray``에서 ``StringName[]``로 변경합니다.	✔️	❌	❌	GH-110767
시그널 current_animation_changed``는 ``name 매개변수 유형을 ``String``에서 ``StringName``로 변경합니다.	✔️	❌	❌	GH-110767

3D

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
SpringBoneSimulator3D
메서드 ``get_end_bone_direction``는 반환 유형을 ``SpringBoneSimulator3D.BoneDirection``에서 ``SkeletonModifier3D.BoneDirection``로 변경합니다.	✔️	❌	✔️	GH-110120
메서드 ``get_joint_rotation_axis``는 반환 유형을 ``SpringBoneSimulator3D.RotationAxis``에서 ``SkeletonModifier3D.RotationAxis``로 변경합니다.	✔️	❌	✔️	GH-110120
메서드 ``get_rotation_axis``는 반환 유형을 ``SpringBoneSimulator3D.RotationAxis``에서 ``SkeletonModifier3D.RotationAxis``로 변경합니다.	✔️	❌	✔️	GH-110120
메소드 set_end_bone_direction``는 ``bone_direction 매개변수 유형을 ``SpringBoneSimulator3D.BoneDirection``에서 ``SkeletonModifier3D.BoneDirection``로 변경합니다.	✔️	❌	✔️	GH-110120
메소드 set_joint_rotation_axis``는 ``axis 매개변수 유형을 ``SpringBoneSimulator3D.RotationAxis``에서 ``SkeletonModifier3D.RotationAxis``로 변경합니다.	✔️	❌	✔️	GH-110120
메소드 set_rotation_axis``는 ``axis 매개변수 유형을 ``SpringBoneSimulator3D.RotationAxis``에서 ``SkeletonModifier3D.RotationAxis``로 변경합니다.	✔️	❌	✔️	GH-110120

렌더링

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
Server
accessibility_create_sub_text_edit_elements 메소드는 새로운 is_last_line 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	|✔️ 호환 가능|	GH-113459
tts_speak 메소드는 utterance_id 매개변수 유형 메타데이터를 ``int32``에서 ``int64``로 변경합니다.	✔️	|✔️ 호환 가능|	|✔️ 호환 가능|	GH-112379

노드 만들기

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
Control
grab_focus 메소드는 새로운 hide_focus 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	|✔️ 호환 가능|	GH-110250
has_focus 메소드는 새로운 ignore_hidden_focus 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	|✔️ 호환 가능|	GH-110250
파일 대화 상자
add_filter 메소드는 새로운 mime_type 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	|✔️ 호환 가능|	GH-111439
텍스처
edit 메소드는 새로운 hide_focus 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	|✔️ 호환 가능|	GH-111117
뷰포트
clamp_split_offset 메소드는 새로운 priority_index 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	|✔️ 호환 가능|	GH-90411

네트워킹

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
저장공간
메서드 ``disconnect_from_host``가 기본 클래스 ``StreamPeerSocket``로 이동되었습니다.	✔️	✔️	✔️	GH-107954
메서드 ``get_status``가 기본 클래스 ``StreamPeerSocket``로 이동되었습니다.	✔️	❌	✔️	GH-107954
메서드 ``poll``가 기본 클래스 ``StreamPeerSocket``로 이동되었습니다.	✔️	✔️	✔️	GH-107954
텍스처
메서드 ``is_connection_available``가 기본 클래스 ``SocketServer``로 이동되었습니다.	✔️	✔️	✔️	GH-107954
메서드 ``is_listening``가 기본 클래스 ``SocketServer``로 이동되었습니다.	✔️	✔️	✔️	GH-107954
메서드 ``stop``가 기본 클래스 ``SocketServer``로 이동되었습니다.	✔️	✔️	✔️	GH-107954

OpenXR

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
Expression Node(표현식 노드)
_get_requested_extensions 메소드는 새로운 xr_version 매개변수를 추가합니다.	❌	❌	❌	GH-109302
_set_instance_create_info_and_get_next_pointer 메소드는 새로운 xr_version 매개변수를 추가합니다.	NAN	NAN	NAN	GH-109302

참고

OpenXRExtensionWrapper 유형은 GDExtensions에서 하위 클래스로 분류됩니다. _set_instance_create_info_and_get_next_pointer 메서드에는 void* 매개 변수가 있으므로 스크립팅에 노출되지 않습니다.

편집기

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
EditorExportPlatform
메서드 ``get_script_export_mode``는 반환 유형을 ``int``에서 ``EditorExportPreset.ScriptExportMode``로 변경합니다.	✔️	❌	❌	GH-107167
플러그인:
메서드 ``add_filter``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``add_option``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
add_side_menu 방법이 제거되었습니다.	|❌ 스텁 포함|	|❌ 스텁 포함|	|❌ 스텁 포함|	GH-111162
메서드 ``clear_filename_filter``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``clear_filters``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``get_filename_filter``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``get_line_edit``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``get_option_default``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``get_option_name``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``get_option_values``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``get_selected_options``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``get_vbox``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``invalidate``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``popup_file_dialog``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``set_filename_filter``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``set_option_default``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``set_option_name``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
메서드 ``set_option_values``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
access 속성이 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	❌	✔️	GH-111212
current_dir 속성이 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
current_file 속성이 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
current_path 속성이 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
display_mode 속성이 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	❌	✔️	GH-111212
file_mode 속성이 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	❌	✔️	GH-111212
filters 속성이 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
option_count 속성이 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
show_hidden_files 속성이 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	✔️	✔️	GH-111212
시그널 ``dir_selected``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	❌	✔️	GH-111212
시그널 ``filename_filter_changed``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	❌	✔️	GH-111212
시그널 ``file_selected``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	❌	✔️	GH-111212
시그널 ``files_selected``가 기본 클래스 ``FileDialog``로 이동되었습니다.	✔️	❌	✔️	GH-111212

행동 변화

Android

참고

Android 내보내기 템플릿의 소스 세트 구성이 기본 Android Studio 프로젝트 구조(GH-110829)와 일치하도록 업데이트되었습니다. 이는 Android 프로젝트의 디렉터리 레이아웃에 영향을 미칩니다.

• 이전에 ``[Project root]/android/build/src/``에 있던 파일은 이제 ``[Project root]/android/build/src/main/java/``에 있습니다.

• Android 매니페스트 파일 및 자산 디렉터리가 src/main/ 하위 디렉터리로 이동되었습니다.

예를 들어, ``GodotApp.java``는 ``src/com/godot/game/GodotApp.java``에서 ``src/main/java/com/godot/game/GodotApp.java``로 이동되었습니다.

코어

참고

The TSCN 파일 형식 has changed in two ways in Godot 4.6:

• load_steps is no longer written in scene files (GH-103352). This attribute wasn't used by the editor.

• Unique node IDs are now saved to scene files to help track nodes when they are moved or renamed (GH-106837). This makes scene refactoring significantly more robust.

The changes are backwards-compatible and forwards-compatible, which means scenes saved in Godot 4.5 can still be loaded in Godot 4.6 and vice-versa (notwithstanding other incompatible changes performed in the scene itself).

As a result, when saving a scene that was last edited in Godot 4.5 in Godot 4.6, significant diffs will occur in version control programs. These diffs are expected.

As a reminder, you can upgrade all files in a project to the latest format using Project > Tools > Upgrade Project Files... in the editor, then committing the changes to version control. This allows you to avoid large diffs later on when editing scenes.

렌더링

참고

The default blend mode for Glow is now Screen, which looks more correct but is significantly brighter than the previous Soft Light mode (GH-110671).

Several other glow defaults were changed to ensure the glow didn't become too strong, but you will likely need to tweak glow properties in Environment after upgrading.

In addition, glow's Soft Light blend mode now always behaves as it did previously with use_hdr_2d, regardless of the Viewport's use_hdr_2d setting (GH-109971).

When using the Mobile renderer, the rewritten glow effect will look significantly different to the previous one for performance reasons (GH-110077). You may need to further adjust glow settings in Environment to achieve a similar look to before.

참고

Volumetric fog blending has been changed to be more physically accurate (GH-112494). This will cause volumetric fog to appear brighter in most scenes.

To compensate for this, you will need to decrease volumetric fog density or brightness in Environment, or decrease the Volumetric Fog Energy property on specific lights.

내비게이션

참고

AStar2D.get_point_path, AStar3D.get_point_path, AStarGrid2D.get_id_path 및 ``AStarGrid2D.get_point_path``는 이제 ``from_id``가 비활성화/고체 지점(GH-113988)인 경우 빈 경로를 반환합니다.

변경된 기본값

다음 기본값이 변경되었습니다. 프로젝트가 이전 기본값을 사용하는 경우 이를 이전 값으로 명시적으로 설정해야 할 수도 있습니다.

참고

새로 생성된 프로젝트에 대한 Windows의 기본 렌더링 드라이버는 이제 D3D12 (GH-113213)입니다. 이는 rendering/rendering_device/driver.windows 아래의 프로젝트 설정에서 변경할 수 있습니다.

참고

새로 생성된 프로젝트의 기본 3D 물리 엔진은 이제 Jolt Physics(GH-105737)입니다. 이는 physics/3d/physics_engine 아래의 프로젝트 설정에서 변경할 수 있습니다.

3D

멤버	값	값	소개
씬 인스턴스하기
설명	$NodePath	$NodePath	GH-112267

참고

``skeleton``의 기본값이 변경되었습니다. 호환성을 위해 이전 동작이 필요한 경우 프로젝트 설정에서 ``animation/compatibility/default_parent_skeleton_in_mesh_instance_3d``를 활성화합니다.

렌더링

멤버	값	값	소개
프로젝트 설정
속성 rendering/reflections/sky_reflections/roughness_layers	8	7	GH-107902
속성 rendering/rendering_device/d3d12/agility_sdk_version	613	618	GH-114043
환경
속성 glow_blend_mode	2	1	GH-110671
속성 glow_intensity	0.8	0.3	GH-110671
속성 glow_levels/2	0.0	0.8	GH-110671
속성 glow_levels/3	1.0	0.4	GH-110671
속성 glow_levels/4	0.0	0.1	GH-110671
속성 glow_levels/5	1.0	0.0	GH-110671
속성 ssr_depth_tolerance	0.2	0.5	GH-111210

노드 만들기

매개변수	값	값	소개
팝업메뉴
속성 submenu_popup_delay	0.3	0.2	GH-110256
ResourceImporterCSV번역
속성 compress	'값'	1	GH-112073