If you're encountering an issue with lsfg-vk, this guide will help you create a proper bug report. Vague reports like "it doesn't work" or "this is broken" are not helpful. The more information you provide, the faster we can identify and fix the problem.

With the latest version of lsfg-vk, a debug build is no longer required for most troubleshooting (unless you're performing deep-dive debugging).

Follow these steps to gather the necessary information for your report.

Enabling Vulkan Validation Layers and debug logging provides crucial diagnostic messages that help us understand the root cause of your issue.

Install the vulkan-validation-layers package using your distribution's package manager:

sudo pacman -S vulkan-validation-layers

sudo apt install vulkan-validationlayers

sudo dnf install vulkan-validation-layers

nix-shell -p vulkan-validation-layers

Set the following environment variables to enable verbose logging:

• VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation
• VK_LOADER_DEBUG=all

The method for capturing log output depends on how you launch your application.

If you are running the game or application from your terminal, append 2>&1 | tee output.log to your command. This will redirect all output (including debug messages) to both your console and a file named output.log in your current directory.

Example:

VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation VK_LOADER_DEBUG=all <your app> 2>&1 | tee output.log

If you are running a game through Steam, follow these steps:

1. Clear existing log: Before launching the game, clear Steam's console log file to ensure you only capture relevant output for the current session.

   truncate -s 0 ~/.steam/steam/logs/console-linux.txt

2. Set Steam Launch Options: Go to the game's properties in Steam, then navigate to "Launch Options" and add the following:

   VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation VK_LOADER_DEBUG=all %command%

3. Launch the game: Start the game normally from your Steam library.

In addition to the log file (output.log or console-linux.txt), please include the following details about your environment and the issue itself:

1. Linux Distribution: Which Linux distribution are you using (e.g., Ubuntu 22.04, Fedora 39, Arch Linux)?
2. Linux Familiarity: How familiar are you with Linux (e.g., newcomer, intermediate, experienced)? This helps us tailor our advice.
3. liblsfg-vk.so Origin: How did you obtain the liblsfg-vk.so file? Did you use a pre-built package (e.g., .deb, .rpm, .tar.zst), unzip a generic .zip, or compile it from source? If compiled, please specify how.
4. Game Launch Method: Are you running the game through Steam (Proton or Native)? Have you tried running it directly from the command line without Steam?
5. Game Type: Is the game running natively on Linux or is it a Windows game running via Proton/Wine?
6. Gamescope Usage: Are you using Gamescope?
7. Issue Description: Detail exactly what you are encountering. Be as specific as possible.
8. Visual Evidence: Attach photos or videos if possible. These are often invaluable for diagnosing visual bugs.
9. Regression Information: Did this work before? If so, what changed in your setup (e.g., updated lsfg-vk version, driver update, game update)?

Once you have gathered all the information, you can open a new issue on the Issues page.

Please be patient while waiting for a response; the maintainer may be extremely busy! <3