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 사용 중 발생하는 일반적인 문제와 가능한 해결 방법이 나열되어 있습니다.

더 보기

Godot 편집기의 웹 버전에 대한 특정 주의 사항은 웹 편집기 사용하기를 참조하세요.

편집기가 느리게 실행되며 모든 CPU 및 GPU 리소스를 사용해서 내 컴퓨터를 시끄럽게 만듭니다

이 문제는 특히 macOS에서 잘 알려진 문제입니다. 대부분의 Mac에는 Retina 디스플레이가 내장되어 있습니다. Retina 디스플레이는 높은 픽셀 밀도를 가지고 있기 때문에, 모든 것을 고해상도로 렌더링해야 합니다. 이는 GPU의 부하가 증가하고 성능이 저하됩니다.

여기에 성능과 배터리 수명을 향상시키는 몇 가지 방법이 있습니다:

  • 3D에서, 왼쪽 상단에 있는 원근 버튼을 클릭하고 절반 해상도를 활성화하면 3D 뷰포트가 절반의 해상도로 최대 4배 빠르게 렌더링됩니다.

  • 편집기 설정을 열고 낮은 프로세서 모드 슬립 (µsec)의 값을 33000(30 FPS)으로 늘립니다. 이 값은 렌더링할 프레임 사이의 마이크로초의 양을 결정합니다. 값이 높으면 편집기의 반응성이 떨어지지만 CPU 및 GPU 사용량을 크게 줄일 수 있습니다.

  • 편집기가 (입자와 같이) 계속해서 다시 그리게 하는 노드가 있는 경우 _ready() 메서드에서 스크립트를 사용하여 이를 숨기고 보여줍니다. 이렇게 하면 편집기에서 숨겨지지만 실행 중인 프로젝트에서는 여전히 표시될 것입니다.

가변 새로 고침 빈도 모니터(G-Sync/FreeSync)에서 편집기가 버벅거리고 깜박거립니다

이는 `알려진 문제 <https://github.com/godotengine/godot/issues/38219>`__입니다. 가변 주사율 모니터는 시간이 지나도 일정한 양의 빛을 방출하기 위해 감마 곡선을 지속적으로 조정해야 합니다. 이는 새로 고침 빈도가 많이 다를 때 이미지의 어두운 영역에 깜박임이 나타날 수 있으며, 이는 Godot 편집기가 필요할 때만 다시 그리기 때문에 발생합니다.

이 문제에 대한 여러 해결 방법이 있습니다:

  • 편집기 설정에서 인터페이스 > 편집기 > 상시 업데이트를 활성화하세요. 이 기능을 활성화하면 화면에 아무 변화가 없더라도 편집기가 계속 렌더링되므로 전력 사용량과 발열/소음 발생이 증가합니다. 이를 완화하려면 편집기 설정에서 낮은 프로세서 모드 슬립 (µsec)을 33000(30 FPS)으로 늘릴 수 있습니다. 이 값은 렌더링할 프레임 사이의 마이크로초의 양을 결정합니다. 값이 높으면 편집기의 반응성이 떨어지지만 CPU 및 GPU 사용량을 크게 줄일 수 있습니다.

  • 또는 모니터나 그래픽 드라이버에서 가변 재생 빈도를 비활성화하세요.

  • 모니터 OSD의 VRR 제어 또는 어두운 영역 미세 조정 옵션을 사용하여 일부 디스플레이에서 VRR 깜박임을 줄일 수 있습니다. 이러한 옵션을 사용하면 입력 지연이 증가하거나 검은색이 깨질 수 있습니다.

  • OLED 디스플레이를 사용하는 경우 편집기 설정에서 Black (OLED) 편집기 테마 사전 설정을 사용하세요. 이는 OLED의 완벽한 블랙 레벨 덕분에 VRR 깜박임을 숨깁니다.

편집기나 프로젝트가 시작되는 데 너무 오랜 시간이 걸립니다

RenderingDevice 기반 렌더러(Forward+ 또는 Mobile) 중 하나를 사용하는 경우 첫 번째 시작 시간이 비교적 길어질 것으로 예상됩니다. 이는 셰이더를 캐시하기 전에 컴파일해야 하기 때문입니다. 셰이더는 또한 Godot 업데이트 후, 그래픽 드라이버 업데이트 후 또는 그래픽 카드 전환 후 다시 캐시되어야 합니다.

이는 특정 USB 주변 장치가 연결되어 있을 때 Windows에서 발생하는 '알려진 버그 <https://github.com/godotengine/godot/issues/20566>'__입니다. 특히, Corsair의 iCUE 소프트웨어가 버그를 일으키는 것 같습니다. USB 주변 기기의 드라이버를 최신 버전으로 업데이트해 보세요. 버그가 지속되면 편집기를 열기 전에 결함이 있는 주변 장치를 분리해야 합니다. 그런 다음 주변 장치를 다시 연결할 수 있습니다.

Portmaster와 같은 방화벽 소프트웨어로 인해 디버그 포트가 차단될 수도 있습니다. 이로 인해 프로젝트를 시작하는 데 오랜 시간이 걸리며 편집기에서 디버깅 기능(예: print() 출력 보기)을 사용할 수 없습니다. 에디터 세팅(네트워크 > 디버그 > 원격 포트)에서 프로젝트에 사용되는 디버그 포트를 변경하면 이 문제를 해결할 수 있습니다. 기본값은 ``6007``입니다. ``7007``와 같이 ``1024``보다 큰 다른 값을 사용해 보세요.

Windows에서 PC를 켠 후 처음으로 프로젝트를 로드하면 Windows Defender로 인해 프로젝트 시작 시 파일 시스템 캐시 유효성 검사에 훨씬 더 오랜 시간이 걸립니다. 이는 파일 수가 많은 프로젝트에서 특히 두드러집니다. 바이러스 및 위협 방지 > 바이러스 및 위협 방지 설정 > 제외 추가 또는 제거로 이동하여 제외 목록에 프로젝트 폴더를 추가하는 것을 고려해보세요.

시스템 콘솔을 클릭하면 Godot 편집기가 고정된 것처럼 보입니다.

시스템 콘솔을 활성화한 Windows에서 Godot를 실행할 때, 명령 창 내부를 클릭해 실수로 선택 모드를 활성화할 수 있습니다. 이 Windows 관련 동작은 응용 프로그램을 일시 정지하여 시스템 콘솔 내에서 텍스트를 선택할 수 있도록 합니다. Godot는 이 시스템 전용 동작을 바꿀 수 없습니다.

이것을 해결하려면 시스템 콘솔 창을 선택하고 Enter를 눌러 선택 모드를 종료하세요.

Godot 편집기의 macOS 도크 아이콘은 수동으로 이동할 때마다 복제됩니다.

Godot 편집기를 열고 도크 아이콘의 위치를 수동으로 변경한 다음 편집기를 다시 시작하면 도크 오른쪽 끝까지 중복된 도크 아이콘이 표시됩니다.

이는 macOS 도크의 설계 제한 때문입니다. 이 문제를 해결하는 알려진 유일한 방법은 프로젝트 관리자와 편집기를 단일 프로세스로 병합하는 것입니다. 즉, 프로젝트 관리자는 편집기를 시작할 때 더 이상 별도의 프로세스를 생성하지 않습니다. 단일 프로세스 인스턴스를 사용하면 여러 가지 이점이 있지만 작업의 복잡성으로 인해 가까운 시일 내에 이를 수행할 계획은 없습니다.

이 문제를 피하려면, Godot 편집기의 독 아이콘을 macOS에서 만든 기본 위치에 유지시키세요.

프로젝트 매니저 및 편집기 창의 왼쪽 위 구석에 "NO DC"와 같은 텍스트가 나타납니다.

이것은 NVIDIA 그래픽 드라이버가 정보를 표시하기 위해 오버레이를 삽입하기 때문에 발생합니다.

Windows에서 이 오버레이를 비활성화하려면, 그래픽 드라이버 설정을 NVIDIA 제어판의 기본값으로 복원하세요.

Linux에서 이 오버레이를 비활성화하려면, nvidia-settings을 열고, X Screen 0 > OpenGL Settings에서 Enable Graphics API Visual Indicator를 선택 취소하세요.

프로젝트 매니저 및 편집기 창의 왼쪽 위 구석에 "NO DC"와 같은 텍스트가 나타납니다.

이는 ShadowPlay 녹화 시 즉각적인 재생 정보를 표시하기 위해 오버레이를 삽입하는 NVIDIA 그래픽 드라이버로 인해 발생합니다. Linux는 ShadowPlay를 지원하지 않으므로 이 오버레이는 Windows에서만 볼 수 있습니다.

이 오버레이를 비활성화하려면 :kbd:`Alt + Z`(NVIDIA 오버레이의 기본 단축키)를 누르고 NVIDIA 오버레이에서 **설정 > HUD 레이아웃 > 상태 표시기**를 비활성화하세요.

또는 GeForce Experience를 대체하고 이 문제가 발생하지 않는 `new NVIDIA app <https://www.nvidia.com/en-us/software/nvidia-app/>`를 설치할 수 있습니다. GeForce Experience와 달리 NVIDIA 앱은 각 창 모서리가 아닌 화면 모서리에 재생 표시기를 그립니다.

편집기나 프로젝트가 지나치게 날카롭거나 흐리게 보여집니다

올바른 모양(왼쪽), 그래픽 드라이버 선명화로 인해 과도하게 선명해진 모양(오른쪽)

올바른 모양(왼쪽), 그래픽 드라이버 선명화로 인해 과도하게 선명해진 모양(오른쪽)

편집기나 프로젝트가 지나치게 선명하게 나타나는 경우 이는 그래픽 드라이버가 모든 Vulkan 또는 OpenGL 응용 프로그램에 강제로 이미지 선명하게 하기 때문일 수 있습니다. 그래픽 드라이버 제어판에서 이 동작을 비활성화할 수 있습니다.

  • NVIDIA(Windows): 시작 메뉴를 열고 NVIDIA 제어판**을 선택합니다. 왼쪽에서 **3D 설정 관리 탭을 엽니다. 중앙 목록에서 **이미지 선명화**로 스크롤하여 **선명화 끄기**로 설정합니다.

  • AMD(Windows): 시작 메뉴를 열고 AMD 소프트웨어**를 선택합니다. 오른쪽 상단에 있는 설정 "톱니바퀴" 아이콘을 클릭하세요. **그래픽 탭으로 이동한 다음 **Radeon Image Sharpening**을 비활성화합니다.

편집기나 프로젝트가 지나치게 흐릿하게 나타나는 경우 이는 그래픽 드라이버가 :abbr:`FXAA(Fast Approximate AntiAliasing)`를 모든 Vulkan 또는 OpenGL 애플리케이션에 강제로 적용했기 때문일 수 있습니다.

  • NVIDIA(Windows): 시작 메뉴를 열고 NVIDIA 제어판**을 선택합니다. 왼쪽에서 **3D 설정 관리 탭을 엽니다. 중간 목록에서 **Fast Approximate Antialiasing**으로 스크롤하여 **Application Controlled**로 설정합니다.

  • NVIDIA(Linux): 애플리케이션 메뉴를 열고 **NVIDIA X 서버 설정**을 선택합니다. 왼쪽에서 **앤티앨리어싱 설정**을 선택한 다음 **FXAA 활성화**를 선택 취소합니다.

  • AMD(Windows): 시작 메뉴를 열고 AMD 소프트웨어**를 선택합니다. 오른쪽 상단에 있는 설정 "톱니바퀴" 아이콘을 클릭하세요. **그래픽 탭으로 이동하여 하단으로 스크롤한 후 **고급**을 클릭하여 설정을 펼칩니다. **형태학적 안티앨리어싱**을 비활성화합니다.

vkBasalt와 같은 타사 공급업체 독립적 유틸리티도 모든 Vulkan 애플리케이션에서 선명화 또는 FXAA를 강제할 수 있습니다. 구성도 확인하고 싶을 수도 있습니다.

그래픽 드라이버나 타사 유틸리티에서 옵션을 변경한 후 Godot를 다시 시작하여 변경 사항을 적용하세요.

다른 응용 프로그램에서 선명화 또는 FXAA를 강제로 적용하려면 그래픽 드라이버 제어판에서 제공하는 응용 프로그램 프로필 시스템을 사용하여 응용 프로그램별로 수행하는 것이 좋습니다.

PC를 절전 상태에서 다시 시작하면 편집기/프로젝트가 멈추거나 화면이 망가진 듯 표시됩니다

이는 독점 드라이버를 사용할 때 NVIDIA 그래픽이 탑재된 Linux에서 알려진 문제입니다. Linux + NVIDIA에서 OpenGL 또는 Vulkan이 관련되면 종종 버그가 발생하므로 아직 확실한 수정 사항은 없습니다. OpenGL을 사용하는 호환성 렌더링 방법은 일반적으로 Vulkan을 사용하는 Forward+ 및 모바일 렌더러에 비해 일시 중지 관련 문제가 발생할 가능성이 적습니다.

NVIDIA 드라이버는 이 문제를 해결할 수 있는 실험적 `일시 중지 후 비디오 메모리를 보존하는 옵션 <https://wiki.archlinux.org/title/NVIDIA/Tips_and_tricks#Preserve_video_memory_after_suspend>`__를 제공합니다. 이 옵션은 최신 NVIDIA 드라이버 버전에서 더 잘 작동하는 것으로 보고되었습니다.

작업 손실을 방지하려면 PC를 절전 모드로 전환하기 전에 편집기에서 장면을 저장하세요.

편집기에서는 프로젝트가 잘 실행되지만 내보낸 사본에서 프로젝트를 실행할 시 일부 파일을 불러올 수 없습니다

이는 내보내기 대화 상자에서 리소스 파일이 아닌 파일의 필터링을 특정하지 않아 발생하는 오류입니다. 기본적으로 Godot는 PCK 파일에 실제 리소스만을 포함하고 있습니다. JSON 파일과 같이 일반적으로 자주 사용되는 일부 파일 형식은 리소스로 취급하지 않습니다. 예를 들어, 내보낸 프로젝트에서 test.json 파일을 불러오는 경우 비 리소스 내보내기 필터에서 *.json 파일 형식을 특정해야 합니다. 자세한 정보는 리소스 옵션를 참조하세요.

또한 이름이 마침표로 시작하는 파일 및 폴더는 내보낸 프로젝트에 포함되지 않습니다. 이는 ``.git``와 같은 버전 제어 폴더가 내보낸 PCK 파일에 포함되는 것을 방지하기 위해 수행됩니다.

Windows의 대소문자 구분 문제 때문일 수도 있습니다. 파일시스템과 다른 대소문자를 사용하여 스크립트에서 리소스를 참조하는 경우 프로젝트를 내보내면 리소스 로드가 실패합니다. 가상 PCK 파일시스템은 대소문자를 구분하지만, Windows의 파일시스템은 기본적으로 대소문자를 구분하지 않기 때문입니다.

프로젝트 관리자에서 프로젝트를 연 후 자주 또는 즉시 충돌이 발생합니다.

이는 편집기 플러그인, GDExtension 애드온 등 다양한 원인으로 인해 발생할 수 있습니다. 이 시나리오에서는 복구 모드에서 프로젝트를 열고 충돌을 일으키는 원인을 찾아 수정하는 것이 좋습니다. 자세한 내용은 :ref:`프로젝트 관리자 페이지 <doc_project_manager>`를 참조하세요.