Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

문제 해결

이 페이지에는 Godot 사용 중 발생하는 일반적인 문제와 가능한 해결 방법이 나열되어 있습니다.

더 보기

웹 버전 Godot 에디터에 대한 주의 사항은 웹 에디터 사용하기를 참고하세요.

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

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

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

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

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

  • 편집기가 (파티클과 같이) 계속해서 다시 그리게 하는 노드가 있는 경우, 이 노드를 숨기고 _ready() 메서드의 스크립트를 사용해서 표시합니다. 이렇게 하면 편집기서에는 숨겨지지만 실행 중인 프로젝트서에는 계속 표시됩니다.

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

This is a known issue. Variable refresh rate monitors need to adjust their gamma curves continuously to emit a consistent amount of light over time. This can cause flicker to appear in dark areas of the image when the refresh rate varies a lot, which occurs as the Godot editor only redraws when necessary.

There are several workarounds for this:

  • Enable Interface > Editor > Update Continuously in the Editor Settings. Keep in mind this will increase power usage and heat/noise emissions since the editor will now be rendering constantly, even if nothing has changed on screen. To alleviate this, you can increase Low Processor Mode Sleep (µsec) to 33000 (30 FPS) in the Editor Settings. This value determines the amount of microseconds between frames to render. Higher values will make the editor feel less reactive but will help decrease CPU and GPU usage significantly.

  • Alternatively, disable variable refresh rate on your monitor or in the graphics driver.

  • VRR flicker can be reduced on some displays using the VRR Control or Fine Tune Dark Areas options in your monitor's OSD. These options may increase input lag or result in crushed blacks.

  • If using an OLED display, use the Black (OLED) editor theme preset in the Editor Settings. This hides VRR flicker thanks to OLED's perfect black levels.

에디터 및 프로젝트가 켜지기까지 너무 오랜 시간이 걸립니다

When using one of the Vulkan-based renderers (Forward+ or Forward Mobile), the first startup is expected to be relatively long. This is because shaders need to be compiled before they can be cached. Shaders also need to be cached again after updating Godot, after updating graphics drivers or after switching graphics cards.

If the issue persists after the first startup, this is a known bug on Windows when you have specific USB peripherals connected. In particular, Corsair's iCUE software seems to cause this bug. Try updating your USB peripherals' drivers to their latest version. If the bug persists, you need to disconnect the specific peripheral before opening the editor. You can then connect the peripheral again.

Firewall software such as Portmaster may also cause the debug port to be blocked. This causes the project to take a long time to start, while being unable to use debugging features in the editor (such as viewing print() output). You can work this around by changing the debug port used by the project in the Editor Settings (Network > Debug > Remote Port). The default is 6007; try another value that is greater than 1024, such as 7007.

The Godot editor appears frozen after clicking the system console

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

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

The Godot editor's macOS dock icon gets duplicated every time it is manually moved

If you open the Godot editor and manually change the position of the dock icon, then restart the editor, you will get a duplicate dock icon all the way to the right of the dock.

This is due to a design limitation of the macOS dock. The only known way to resolve this would be to merge the project manager and editor into a single process, which means the project manager would no longer spawn a separate process when starting the editor. While using a single process instance would bring several benefits, it isn't planned to be done in the near future due to the complexity of the task.

To avoid this issue, keep the Godot editor's dock icon at its default location as created by macOS.

Some text such as "NO DC" appears in the top-left corner of the Project Manager and editor window

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

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

리눅스에서 이 오버레이 사용을 중지하려면, nvidia-settings을 열고, X Screen 0 > OpenGL Setting에서 Enable Graphics API Visual Indicator를 선택 취소합니다.

에디터 또는 프로젝트가 지나치게 날카롭거나 흐리게 표시됩니다

Correct appearance (left), oversharpened appearance due to graphics driver sharpening (right)

Correct appearance (left), oversharpened appearance due to graphics driver sharpening (right)

If the editor or project appears overly sharp, this is likely due to image sharpening being forced on all Vulkan or OpenGL applications by your graphics driver. You can disable this behavior in the graphics driver's control panel:

  • NVIDIA (Windows): Open the start menu and choose NVIDIA Control Panel. Open the Manage 3D settings tab on the left. In the list in the middle, scroll to Image Sharpening and set it to Sharpening Off.

  • AMD (Windows): Open the start menu and choose AMD Software. Click the settings "cog" icon in the top-right corner. Go to the Graphics tab then disable Radeon Image Sharpening.

If the editor or project appears overly blurry, this is likely due to FXAA being forced on all Vulkan or OpenGL applications by your graphics driver.

  • NVIDIA (Windows): Open the start menu and choose NVIDIA Control Panel. Open the Manage 3D settings tab on the left. In the list in the middle, scroll to Fast Approximate Antialiasing and set it to Application Controlled.

  • NVIDIA (Linux): Open the applications menu and choose NVIDIA X Server Settings. Select to Antialiasing Settings on the left, then uncheck Enable FXAA.

  • AMD (Windows): Open the start menu and choose AMD Software. Click the settings "cog" icon in the top-right corner. Go to the Graphics tab, scroll to the bottom and click Advanced to unfold its settings. Disable Morphological Anti-Aliasing.

Third-party vendor-independent utilities such as vkBasalt may also force sharpening or FXAA on all Vulkan applications. You may want to check their configuration as well.

After changing options in the graphics driver or third-party utilities, restart Godot to make the changes effective.

If you still wish to force sharpening or FXAA on other applications, it's recommended to do so on a per-application basis using the application profiles system provided by graphics drivers' control panels.

The editor or project appears to have washed out colors

On Windows, this is usually caused by incorrect OS or monitor settings, as Godot currently does not support HDR output (even though it may internally render in HDR).

As most displays are not designed to display SDR content in HDR mode, it is recommended to disable HDR in the Windows settings when not running applications that use HDR output. On Windows 11, this can be done by pressing Windows + Alt + B (this shortcut is part of the Xbox Game Bar app). To toggle HDR automatically based on applications currently running, you can use AutoActions.

If you insist on leaving HDR enabled, it is possible to somewhat improve the result by ensuring the display is configured to use HGIG tonemapping (as opposed to DTM), then using the Windows HDR calibration app. It is also strongly recommended to use Windows 11 instead of Windows 10 when using HDR. The end result will still likely be inferior to disabling HDR on the display, though.

Support for HDR output is planned in a future release.

The editor/project freezes or displays glitched visuals after resuming the PC from suspend

This is a known issue on Linux with NVIDIA graphics when using the proprietary driver. There is no definitive fix yet, as suspend on Linux + NVIDIA is often buggy when OpenGL or Vulkan is involved. The Compatibility rendering method (which uses OpenGL) is generally less prone to suspend-related issues compared to the Forward+ and Forward Mobile rendering methods (which use Vulkan).

The NVIDIA driver offers an experimental option to preserve video memory after suspend which may resolve this issue. This option has been reported to work better with more recent NVIDIA driver versions.

To avoid losing work, save scenes in the editor before putting the PC to sleep.

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

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

Also, note that files and folders whose names begin with a period will never be included in the exported project. This is done to prevent version control folders like .git from being included in the exported PCK file.

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