トラブルシューティング

このページでは、Godotを使用する際によく遭遇する問題と、その解決策の候補を一覧にしています。

参考

Web版のGodotエディタに特有の注意点については、 Webエディタの実行 をご覧ください。

エディターの動作が遅く、CPUとGPUのリソースの多くを使用する場合、コンピュータからの騒音が大きくなります

これは既知の問題であり、ほとんどの Mac には Retina ディスプレイが搭載されているため、特に macOS で発生します。このディスプレイでは、より高い解像度でのエンジンのレンダリングが必要になります。これにより、GPU負荷が増加し、体感的なパフォーマンスが低下します。

パフォーマンスとバッテリー寿命を向上させるには、いくつか方法があります。

  • 3D では、左上隅にある Perspective ボタンをクリックし、 Half Resolution を有効にします。 3D ビューポートは半分の解像度でレンダリングされるようになり、最大 4 倍高速化されます。

  • Open the Editor Settings and increase the value of Low Processor Mode Sleep (µsec) to 33000 (30 FPS). 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.

  • If you have a node that causes the editor to redraw continuously (such as particles), hide it and show it using a script in the _ready() method. This way, it will be hidden in the editor, but will still be visible in the running project.

可変リフレッシュレートモニター(G-Sync/FreeSync)でエディターが途切れたり、チラついたりします

これは既知の問題です。可変リフレッシュ レート モニターは、時間の経過とともに一貫した量の光を放射するために、ガンマ カーブを継続的に調整する必要があります。 これにより、リフレッシュ レートが大幅に変化するときに画像の暗い領域にちらつきが発生する可能性があります。これは、Godot エディタが必要な場合にのみ再描画するために発生します。

これにはいくつかの理由があります:

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

  • お使いのモニターまたはグラフィックス ドライバーで可変リフレッシュ レートを無効にすることもできます。

  • 一部のディスプレイでは、モニターの OSD の VRR コントロール または 暗部の微調整 オプションを使用して、VRR ちらつきを軽減できます。 これらのオプションを使用すると、入力ラグが増加したり、黒が潰れてしまう可能性があります。

  • OLED ディスプレイを使用している場合は、エディター設定でプリセットされている ブラック (OLED) エディター テーマを使用します。 OLED の完璧な黒レベルのおかげで、VRR のちらつきを隠すことができます。

エディタやプロジェクトの開始に非常に時間がかかります

When using one of the RenderingDevice-based renderers (Forward+ or 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.

これはWindows上において、特定のUSB周辺機器を接続している場合に発生する既知のバグです。特に、Corsair の iCUE ソフトウェアがこのバグの原因となっているようです。USB周辺機器のドライバを最新バージョンにアップデートしてみてください。バグが続く場合は、エディタを開く前に問題のある周辺機器を切断する必要があります。その後、再度周辺機器を接続してください。

Portmaster などのファイアーウォールソフトによっても、デバッグ通信がブロックされる可能性があります。これによりプロジェクトの起動に時間がかかり、エディターでデバッグ機能 (print() 出力の表示など) が使用できなくなります。この問題を回避するには、エディター設定 (ネットワーク > デバッグ > リモートポート) で使用できるポートに変更します。デフォルトは 6007 です。 1024 より大きい別の値 (「7007」など) を試してください。

Windowsでは、PCの電源を入れた後にプロジェクトを初めて読み込むと、Windows Defenderがプロジェクトの起動時にファイルシステムキャッシュの検証を行うため、時間が大幅にかかります。これは特にファイル数が多いプロジェクトで顕著です。ウイルスと脅威の保護 > ウイルスと脅威の保護設定 > 除外の追加または削除に移動して、プロジェクトフォルダーを除外リストに追加することを検討してください。

システムコンソールをクリックすると、Godotエディタがフリーズしたように見える

システムコンソールが有効な状態でGodotをWindows上で実行しているとき、コマンドウィンドウの内側をクリックすると誤って 選択モード を有効にしてしまうことがあります。このWindows固有の動作は、システムコンソール内でテキストを選択できるようにアプリケーションを一時停止させます。Godot はこのシステム固有の動作を上書きすることができません。

これを解決するには、システムコンソールウィンドウを選択し、Enterキーを押して選択モードを解除します。

Godot エディタの macOS ドック アイコンを移動するたびに複製される

Godot エディタを開いてドック アイコンの位置を手動で変更し、エディタを再起動すると、ドックの右側に複製のドック アイコンが表示されます。

これは、macOS ドックの設計制限によるものです。 これを解決する唯一の方法は、プロジェクト マネージャーとエディターを 1 つのプロセスにマージすることです。これは、プロジェクト マネージャーがエディターの起動時に別のプロセスを生成しなくなることを意味します。 単一のプロセス インスタンスを使用するといくつかの利点が得られますが、タスクが複雑であるため、近い将来には使用される予定はありません。

この問題を回避するには、Godot エディタのドック アイコンを macOS によって作成されたデフォルトの場所に維持します。

「NO DC」などの文字は稀にプロジェクトマネージャーやエディターの左上に現れることがあります

これは、NVIDIAグラフィックスドライバが情報を表示するためにオーバーレイを挿入することが原因です。

Windowsでこのオーバーレイを無効にするには、NVIDIA Control Panelでグラフィックドライバーの設定をデフォルト値に戻してください。

Linuxでこのオーバーレイを無効にするには、 nvidia-settings を開き、 X Screen 0 > OpenGL Settings を選択し、 Enable Graphics API Visual Indicator のチェックを外します。

マイクロフォンまたは「更新」のアイコンがプロジェクトマネージャーやエディターの右下に現れます

これは、NVIDIA グラフィックドライバーがオーバーレイを挿入して、ShadowPlay 録画のインスタントリプレイ情報を表示することによって発生します。Linux では ShadowPlay がサポートされていないため、このオーバーレイは Windows でのみ表示されます。

このオーバーレイを無効にするには、Alt + Z (NVIDIA オーバーレイのデフォルトのショートカット) を押して、NVIDIA オーバーレイで 設定 > HUD レイアウト > ステータス インジケーター を無効にします。

あるいは、GeForce Experience に代わる、この問題の影響を受けない 新しい NVIDIA アプリ <https://www.nvidia.com/en-us/software/nvidia-app/> をインストールすることもできます。GeForce Experience とは異なり、この NVIDIA アプリは、各ウィンドウの隅ではなく、画面の隅にリプレイインジケーターを描画します。

エディターやプロジェクトが過度にぼやけたり鋭く見える

正しい外観 (左)、グラフィックス ドライバーのシャープ化によるオーバーシャープな外観 (右)

正しい外観 (左)、グラフィックス ドライバーのシャープ化によるオーバーシャープな外観 (右)

エディターまたはプロジェクトが過度に鮮明に見える場合は、グラフィックス ドライバーによってすべての Vulkan または OpenGL アプリケーションで画像の鮮明化が強制されていることが原因である可能性があります。 この動作は、グラフィックス ドライバーのコントロール パネルで無効にすることができます。

  • ** NVIDIA (Windows): ** スタートメニューを開き、 NVIDIA コントロール パネル を選択します。 左側の 3D 設定の管理 タブを開きます。 中央のリストで 画像の鮮明化 までスクロールし 鮮明化オフ に設定します。

  • AMD (Windows): スタート メニューを開き、AMD ソフトウェア を選択します。 右上隅にある設定の「歯車」アイコンをクリックします。 [グラフィックス] タブに移動し、Radeon Image Sharpening を無効にします。

エディターまたはプロジェクトが過度にぼやけて見える場合は、グラフィックス ドライバーによってすべての Vulkan または OpenGL アプリケーションに FXAA が強制されていることが原因である可能性があります。

  • NVIDIA (Windows): スタート メニューを開き、NVIDIA コントロール パネル を選択します。 左側の 3D 設定の管理 タブを開きます。 中央のリストで、アンチエイリアシング - FXAA**までスクロールし、**アプリケーションによるコントロール に設定します。

  • NVIDIA (Linux): アプリケーションを開き NVIDIA X Server Settings の項目を開きます。その後左側の Antialiasing Settings を選び、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 Antialiasing.

vkBasaltのようなサードパーティ製のユーティリティもまた、すべてのVulkanアプリケーションにおいて鮮明化を強制したりFXAAを有効にする可能性があります。それらツールの設定も確認しておくと良いでしょう。

グラフィックスドライバーやサードパーティ製ユーティリティーのオプションを変更した後、Godotを再起動して変更を有効にします。

それでも他のアプリケーションで鮮明化の強制やFXAAを使用したい場合は、グラフィックスドライバーのコントロールパネルでアプリケーション毎に設定することを推奨します。

エディターやプロジェクトが色落ちしているように見える

Windowsでは、これは多くの場合OSやモニターの設定が不正なために発生します。Godotは現在 HDR 出力 をサポートしていません(内部処理にHDRを使用する場合もありますが)。

ほとんどのディスプレイはSDRコンテンツをHDRモードで表示するように設計されていないため<https://tftcentral.co.uk/articles/heres-why-you-should-only-enable-hdr-mode-on-your-pc-when-you-are-viewing-hdr-content> 、HDR出力を使用するアプリケーションを実行していないときは、Windowsの設定でHDRを無効にすることをお勧めします。Windows 11では、 Windows + Alt + B を押すことでこれを行うことができます（このショートカットはXbox Game Barアプリの一部です）。現在実行中のアプリケーションに基づいてHDRを自動的に切り替えるには、 AutoActions<https://github.com/Codectory/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.

HDR 出力 のサポートは将来のリリースで追加される予定です。

スリープしてから復帰するとエディター/プロジェクトが固まったり異常な見た目になる

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 Mobile renderers (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.

作業を失わないよう、PCをスリープさせる前にシーンを保存しましょう。

エディタから実行するとプロジェクトは動作するが、エクスポートしたコピーから実行するといくつかのファイルの読み込みに失敗する

これは通常、エクスポートダイアログでリソース以外のファイルのフィルタを指定するのを忘れたことが原因です。デフォルトでは、Godotは実際の リソース のみをPCKファイルに含めます。JSONファイルのような一般的に使われているファイルはリソースとはみなされません。例えば、test.json をエクスポートしたプロジェクトで読み込む場合、*.json をリソース以外のエクスポートフィルタに指定する必要があります。詳しくはリソースオプションを参照してください。

また、名前がピリオドから始まるファイルやフォルダはエクスポートされるプロジェクトには含まれません。これは .git のようなバージョン管理のフォルダがエクスポートされるPCKファイルに含まれないようにするためです。

Windowsでは、大文字小文字の区別における問題が原因である可能性もあります。スクリプト内のリソースを、ファイルシステム上とは異なる大文字小文字で参照した場合、プロジェクトをエクスポートすると読み込みに失敗します。これは、Windows のファイルシステムがデフォルトで大文字小文字を区別しないのに対し、仮想 PCK ファイルシステムは大文字小文字を区別しているためです。

プロジェクトマネージャーからプロジェクトを開くと、頻繁にもしくは即座にクラッシュする

This could be caused by a number of things such as an editor plugin, GDExtension addon, or something else. In this scenario it's recommended that you open the project in recovery mode, and attempt to find and fix whatever is causing the crashes. See the Project Manager page for more information.