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.0에서 Godot 4.1로 업그레이드

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

깨는 변경사항

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

경고

GDExtension API는 4.1의 호환성을 완전히 깨뜨리므로 아래 표에는 포함되지 않습니다. 자세한 내용은 4.1용 GDExtension 업데이트 섹션을 참조하세요.

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

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

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

코어

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
기저
looking_at 메소드는 새로운 use_model_front 선택적 매개변수를 추가합니다.	✔️	✔️	✔️	GH-76082
오브젝트
메서드 ``get_meta_list``는 반환 유형을 ``PackedStringArray``에서 ``Array[StringName]``로 변경합니다.	✔️	❌	❌	GH-76418
변형
looking_at 메소드는 새로운 use_model_front 선택적 매개변수를 추가합니다.	✔️	✔️	✔️	GH-76082
실행 취소다시 실행
create_action 메소드는 새로운 backward_undo_ops 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	✔️	GH-76688
WorkerThreadPool
메서드 ``wait_for_task_completion``는 반환 유형을 ``void``에서 ``Error``로 변경합니다.	✔️	❌	✔️	GH-77143

애니메이션

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
애니메이션 모드
_process 메소드는 새로운 test_only 매개변수를 추가합니다.	❌	❌	❌	GH-75759
blend_input 메소드는 새로운 test_only 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	✔️	GH-75759
blend_node 메소드는 새로운 test_only 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	✔️	GH-75759
AnimationNodeStateMachinePlayback
메서드 ``get_travel_path``는 반환 유형을 ``PackedStringArray``에서 ``Array[StringName]``로 변경합니다.	✔️	❌	❌	GH-76418

노드

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
PathFollow2D
lookahead 속성이 제거되었습니다.	❌	❌	❌	GH-72842

노드

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
예제
메소드 segment_intersects_convex``는 ``planes 매개변수 유형을 유형이 지정되지 않은 ``Array``에서 ``Array[Plane]``로 변경합니다.	✔️	|✔️ 호환 가능|	❌	GH-76418
씬 인스턴스하기
create_multiple_convex_collisions 메소드는 새로운 settings 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	✔️	GH-72152
Node3D
look_at 메소드는 새로운 use_model_front 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	✔️	GH-76082
look_at_from_position 메소드는 새로운 use_model_front 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	✔️	GH-76082

노드 만들기

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
코드편집
add_code_completion_option 메소드는 새로운 location 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	✔️	GH-75746
ScoreLabel
push_list 메소드는 새로운 bullet 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	✔️	GH-75017
push_paragraph 메소드는 새로운 justification_flags 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	✔️	GH-75250
push_paragraph 메소드는 새로운 tab_stops 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	✔️	GH-76401
씬트리
edit_selected 메소드는 새로운 force_edit 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	✔️	GH-76794

물리

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
변형
priority 속성은 유형을 ``float``에서 ``int``로 변경합니다.	❌	❌	❌	GH-72749
예제
priority 속성은 유형을 ``float``에서 ``int``로 변경합니다.	❌	❌	❌	GH-72749
PhysicsDirectSpaceState2D
메서드 ``collide_shape``는 반환 유형을 ``Array[PackedVector2Array]``에서 ``Array[Vector2]``로 변경합니다.	❌	❌	❌	GH-75260
PhysicsDirectSpaceState3D
메서드 ``collide_shape``는 반환 유형을 ``Array[PackedVector3Array]``에서 ``Array[Vector3]``로 변경합니다.	❌	❌	❌	GH-75260

렌더링

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
RDShader파일
메서드 ``get_version_list``는 반환 유형을 ``PackedStringArray``에서 ``Array[StringName]``로 변경합니다.	✔️	❌	❌	GH-76418
렌더링
메소드 draw_list_begin``는 ``storage_textures 매개변수 유형을 유형이 지정되지 않은 ``Array``에서 ``Array[RID]``로 변경합니다.	✔️	|✔️ 호환 가능|	❌	GH-76418
Server
메서드 ``global_shader_parameter_get_list``는 반환 유형을 ``PackedStringArray``에서 ``Array[StringName]``로 변경합니다.	✔️	❌	❌	GH-76418
결과 시험하기
메소드 add_triangle_fan``는 ``tangents 매개변수 유형을 유형이 지정되지 않은 ``Array``에서 ``Array[Plane]``로 변경합니다.	✔️	|✔️ 호환 가능|	❌	GH-76418

내비게이션

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
내비게이션
메소드 set_velocity``가 ``velocity 속성으로 대체되었습니다.	✔️	❌	❌	GH-69988
time_horizon 속성이 time_horizon_agents 및 ``time_horizon_obstacles``로 분할되었습니다.	❌	❌	❌	GH-69988
내비게이션
속성 ``agent_height_offset``가 ``path_height_offset``로 이름이 변경되었습니다.	❌	❌	❌	GH-69988
ignore_y 속성이 제거되었습니다.	❌	❌	❌	GH-69988
메소드 set_velocity``가 ``velocity 속성으로 대체되었습니다.	✔️	❌	❌	GH-69988
time_horizon 속성이 time_horizon_agents 및 ``time_horizon_obstacles``로 분할되었습니다.	❌	❌	❌	GH-69988
내비게이션
estimate_radius 속성이 제거되었습니다.	❌	❌	❌	GH-69988
메소드 ``get_rid``가 ``get_agent_rid``로 이름이 변경되었습니다.	❌	❌	❌	GH-69988
내비게이션
estimate_radius 속성이 제거되었습니다.	❌	❌	❌	GH-69988
메소드 ``get_rid``가 ``get_agent_rid``로 이름이 변경되었습니다.	❌	❌	❌	GH-69988
내비게이션 메시.
메소드 ``agent_set_callback``가 ``agent_set_avoidance_callback``로 이름이 변경되었습니다.	❌	❌	❌	GH-69988
agent_set_target_velocity 방법이 제거되었습니다.	❌	❌	❌	GH-69988
agent_set_time_horizon 메소드가 agent_set_time_horizon_agents 및 ``agent_set_time_horizon_obstacles``로 분할되었습니다.	❌	❌	❌	GH-69988
내비게이션 메시.
메소드 ``agent_set_callback``가 ``agent_set_avoidance_callback``로 이름이 변경되었습니다.	❌	❌	❌	GH-69988
agent_set_target_velocity 방법이 제거되었습니다.	❌	❌	❌	GH-69988
agent_set_time_horizon 메소드가 agent_set_time_horizon_agents 및 ``agent_set_time_horizon_obstacles``로 분할되었습니다.	❌	❌	❌	GH-69988

네트워킹

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
WebRTCPeerConnectionExtension
메서드 ``_create_data_channel``는 반환 유형을 ``Object``에서 ``WebRTCDataChannel``로 변경합니다.	✔️	❌	✔️	GH-78237

편집기 플러그인

변경	GDScript	C# 바이너리 호환	C# 소스 호환	소개
애니메이션 트리
애니메이션 트리	❌	❌	❌	GH-76413
Godot 인터페이스
EditorInterface 유형은 상속을 ``Node``에서 ``Object``로 변경합니다.	✔️	❌	❌	GH-76176
메소드 set_movie_maker_enabled``가 ``movie_maker_enabled 속성으로 대체되었습니다.	✔️	❌	❌	GH-76176
메소드 is_movie_maker_enabled``가 ``movie_maker_enabled 속성으로 대체되었습니다.	✔️	❌	❌	GH-76176
EditorResourcePreviewGenerator
_generate 메소드는 새로운 metadata 매개변수를 추가합니다.	❌	❌	❌	GH-64628
_generate_from_path 메소드는 새로운 metadata 매개변수를 추가합니다.	❌	❌	❌	GH-64628
EditorUndoRedoManager
create_action 메소드는 새로운 backward_undo_ops 선택적 매개변수를 추가합니다.	✔️	|✔️ 호환 가능|	✔️	GH-76688

행동 변화

4.1에서는 일부 동작 변경 사항이 도입되었으며, 이로 인해 프로젝트를 조정해야 할 수도 있습니다.

변경	소개
뷰포트
입력 이벤트가 SubViewports 및 해당 자식 노드에 도달해야 하는 경우 이제 SubViewportContainer.mouse_filter``는 ``MOUSE_FILTER_STOP 또는 ``MOUSE_FILTER_PASS``여야 합니다. 자세한 내용은 `GH-79271`_를 참조하세요.	GH-57894
모두 마우스 입력 이벤트를 수신해야 하는 다중 계층 SubViewportContainer 노드는 이제 Area2D 노드로 대체되어야 합니다. 자세한 내용은 `GH-79128`_를 참조하세요.	GH-57894
Viewport
물리 선택이 활성화된 Viewport 노드는 이제 자동으로 입력 이벤트를 처리된 것으로 설정합니다. 해결 방법은 `GH-79897`_를 참조하세요.	GH-77595

4.1용 GDExtension 업데이트

심각한 버그를 수정하기 위해 Godot 4.1에서는 바이너리 호환성을 크게 깨고 소스 호환성을 작게 깨뜨려야 했습니다.

이는 Godot 4.0용으로 만들어진 GDExtension이 Godot 4.1용으로 다시 컴파일되어야 함을 의미합니다(godot-cpp의 4.1 분기 사용). 소스 코드를 약간 변경해야 합니다.

당신의 최종 씬은 이렇게 보여야 할 것입니다.

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();
}

그러나 Godot 4.1의 경우 다음과 같아야 합니다:

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();
}

다음과 같은 주의 사항이 있습니다:

1. 첫 번째 인수가 ``const GDExtensionInterface *p_interface``에서 ``GDExtensionInterfaceGetProcAddress p_get_proc_address``로 변경됩니다.

2. 이제 init_obj 변수의 생성자는 첫 번째 매개변수로 ``p_get_proc_address``를 받습니다.

또한 다음과 같이 표시되도록 .gdextension 파일에 추가 compatibility_minimum 줄을 추가해야 합니다.

[configuration]

entry_symbol = "example_library_init"
compatibility_minimum = 4.1

이를 통해 Godot는 GDExtension이 업데이트되었으며 Godot 4.1에서 로드해도 안전하다는 것을 알 수 있습니다.