Up to date

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

Validation layers

Validation layers enable developers to verify their application’s correct use of the Vulkan API. Validation layers can be enabled in both debug and release builds, including in exported projects.

Note

Enabling validation layers has a performance impact, so only enable them when you actually need the output to debug the application.

Windows

Install the Vulkan SDK https://vulkan.lunarg.com/sdk/home, which contains validation layers as part of its default installation. No need to enable any optional features in the installer; installing the core Vulkan SDK suffices. You don’t need to reboot after installing the SDK, but you may need to close and reopen your current terminal.

After installing the Vulkan SDK, run Godot with the --gpu-validation command line argument. You can also specify --gpu-abort which will make Godot quit as soon as a validation error happens. This can prevent your system from freezing if a validation error occurs.

macOS

Warning

Official Godot macOS builds do not support validation layers, as these are statically linked against the Vulkan SDK. Dynamic linking must be used instead.

In practice, this means that using validation layers on macOS requires you to use a Godot build compiled with the use_volk=yes SCons option. Compiling for macOS. If testing validation layers on an exported project, you must recompile the export template and specify it as a custom export template in your project’s macOS export preset.

Install the Vulkan SDK https://vulkan.lunarg.com/sdk/home, which contains validation layers as part of its default installation. No need to enable any optional features in the installer; installing the core Vulkan SDK suffices. You don’t need to reboot after installing the SDK, but you may need to close and reopen your current terminal.

After installing the Vulkan SDK, run a Godot binary that was compiled with use_volk=yes SCons option. Specify the --gpu-validation command line argument. You can also specify --gpu-abort which will make Godot quit as soon as a validation error happens. This can prevent your system from freezing if a validation error occurs.

Linux, *BSD

Install Vulkan validation layers from your distribution’s repositories:

Alpine LinuxArch LinuxDebian/UbuntuFedoraFreeBSDGentooMageiaOpenBSDopenSUSESolus

  1. vulkan-validation-layers
  1. pacman -S vulkan-validation-layers
  1. apt install vulkan-validationlayers
  1. dnf install vulkan-validation-layers
  1. pkg install graphics/vulkan-validation-layers
  1. emerge -an media-libs/vulkan-layers
  1. urpmi vulkan-validation-layers
  1. pkg_add graphics/vulkan-validation-layers
  1. zypper install vulkan-validationlayers
  1. eopkg install -c vulkan-validation-layers

You don’t need to reboot after installing the validation layers, but you may need to close and reopen your current terminal.

After installing the package, run Godot with the --gpu-validation command line argument. You can also specify --gpu-abort which will make Godot quit as soon as a validation error happens. This can prevent your system from freezing if a validation error occurs.

Android

After enabling validation layers on Android, a developer can see errors and warning messages in the adb logcat output.

iOS

Validation layers are currently not supported on iOS.

Web

Validation layers are not supported on the web platform, as there is no support for Vulkan there.

Enabling validation layers

Build validation layers from official sources

To build Android libraries, follow the instructions on Khronos’ repository. After a successful build, the libraries will be located in Vulkan-ValidationLayers/build-android/libs.

Copy libraries

Copy libraries from Vulkan-ValidationLayers/build-android/libs to godot/platform/android/java/app/libs/debug/vulkan_validation_layers.

Your Godot source directory tree should look like on the example below:

  1. godot
  2. |-- platform
  3.     |-- android
  4.         |-- java
  5.             |-- app
  6.                 |-- libs
  7.                     |-- debug
  8.                         |-- vulkan_validation_layers
  9.                             |-- arm64-v8a
  10.                             |-- armeabi-v7a
  11.                             |-- x86
  12.                             |-- x86_64

If the subdirectory libs/debug/vulkan_validation_layers doesn’t exist, create it.

Compile and run the Android app

Linked validation layers are automatically loaded and enabled in Android debug builds. You can use Godot’s One-click deploy feature to quickly test your project with the validation layers enabled.