KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #dsh #dsh-plugin #ai-agent #claude-code #codex #typescript #ai-agents #mcp #cli #rust #deepseek-harness

goverlay

★ 1,432 Open GitHub ↗

Goverlay is an easy graphical interface to configure linux gaming applications

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

---

**Goverlay** is a modern Qt6 GUI application for Linux gamers that puts powerful performance and visual tools behind an easy-to-use interface. It configures **MangoHud**, **vkBasalt**, **vkSumi**, **OptiScaler**, and **Proton environment tweaks** through a visual, card-based layout — generating the config files and launch commands you drop into Steam or Lutris.

Whether you want real-time performance monitoring, post-processing effects, smarter upscaling, DLSS/FSR frame generation, or per-game environment overrides, Goverlay handles it in a few clicks.

This project exists thanks to the amazing work of the original maintainers and contributors behind the core tools.  
I’m just a network engineer who loves Linux and gaming — this is my way of giving something back to the community.

---

## Table of Contents

- [Screenshots](#screenshots)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
  - [Universal Methods](#universal-methods)
    - [Flatpak](#flatpak)
    - [AppImage](#appimage)
  - [Distributions](#distributions)
    - [Arch and derivatives](#arch-and-derivatives)
    - [OpenSUSE](#opensuse)
    - [Solus](#solus)
    - [Fedora / Debian / Ubuntu](#fedora--debian--ubuntu)
  - [Tarball](#tarball)
  - [Building from Source](#building-from-source)
- [Architecture](#architecture)
- [Keyboard Shortcuts](#keyboard-shortcuts)
- [Credits](#credits)
- [Donations](#donations)

---

### Integrated Vulkan Preview (PasCube)
Goverlay ships with **PasCube**, a full Vulkan demo compiled from the PasVulkan engine. It launches automatically (or on demand) to preview your MangoHud, vkBasalt, and vkSumi settings in real time. The demo title bar and overlay display the current GOverlay version.

### Per-Game Config Architecture
When a game is selected, GOverlay switches to **Game Mode**. Each game gets its own XDG-compliant config directory containing:
- `MangoHud.conf`
- `vkBasalt.conf`
- `vkSumi.conf`
- `OptiScaler.ini`
- `fakenvapi.ini`
- `bgmod.conf`
- `bgmod` wrapper binary

The bottom **launch command box** updates to show the game-specific `bgmod` command with `%command%` suffix, ready to paste into Steam.

### bgmod Wrapper
`bgmod` is a compiled Free Pascal binary (not a bash script) that replaces the legacy `fgmod` approach. It:
- Intercepts game execution arguments.
- Exports environment variables from `bgmod.conf`.
- Sets up Wine DLL overrides.
- Copies upscaler binaries/plugins into the game folder on launch.
- Supports launcher EXE replacements and UE Shipping EXE auto-discovery.
- Logs to `/tmp/bgmod.log`, the game directory, and `~/.local/share/goverlay/logs/[Game Name]/`.

An uninstaller binary (`bgmod-uninstaller`) cleanly removes wrapper files and restores original backups.

---

## Screenshots

<details>
<summary>Click to view screenshots</summary>

</details>

---

## Prerequisites

### Required

- [**`mangohud`**](https://github.com/flightlessmango/MangoHud) — Performance overlay / monitoring
- [**`git`**](https://github.com/git/git) — Used to clone repositories (e.g., ReShade shaders)
- [**`qt6pas`**](https://gitlab.com/freepascal.org/lazarus/lazarus/-/tree/main/lcl/interfaces/qt6/cbindings) — Qt6 bindings for Free Pascal / Lazarus
- [**`gamemode`**](https://github.com/FeralInteractive/gamemode) — Feral GameMode daemon (for the GameMode tweak)
- **Nerd Fonts** — Used for icon glyphs in the sidebar and game badges

### Optional / Used by specific features

- [**`vkBasalt`**](https://github.com/DadSchoorse/vkBasalt) — Vulkan post-processing effects
- [**`vksumi`**](https://github.com/reakjra/vkSumi) *(optional but recommended)* — Alternative Vulkan post-processor with 15 tunable parameters
- [**`zenergy`**](https://github.com/BoukeHaarsma23/zenergy) — Displays AMD CPU power metrics in MangoHud
- [**`protontricks`**](https://github.com/Matoking/protontricks) — Proton prefix management (native builds only, disabled in Flatpak)

> [!NOTE]
> In Flatpak, GOverlay hides host-dependent features such as GameMode and Protontricks because it cannot reliably detect or execute host binaries.

---

## Installation

## Universal Methods

### Flatpak

You can download it from [**`Flathub`**](https://flathub.org/en/apps/io.github.benjamimgois.goverlay)

```bash
# Add Flathub repository
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

# Install Goverlay
flatpak install flathub io.github.benjamimgois.goverlay

# Install required Vulkan layers for MangoHud and vkBasalt support
flatpak install flathub org.freedesktop.Platform.VulkanLayer.MangoHud//25.08 \
org.freedesktop.Platform.VulkanLayer.vkBasalt//25.08 -y

# Download vksumi flatpak runtime from its github page and install
https://github.com/reakjra/vkSumi
flatpak install vkSumi-25.08.flatpak

```

### AppImage

Download the AppImage from the [Releases page](https://github.com/benjamimgois/Goverlay/releases) and make it executable:

```bash
chmod +x Goverlay_*.AppImage
./Goverlay_*.AppImage
```

## Distributions

### Arch and derivatives

**Option 1 – Official Repository**
```bash
sudo pacman -S goverlay
```
**Option 2 – AUR**
```bash
yay -S goverlay-git
```

### OpenSUSE
```bash
sudo zypper install goverlay
```

### Solus
```bash
sudo eopkg it goverlay
```

> [!IMPORTANT]
> **Fedora / Debian / Ubuntu users:** Official repositories for these distros often ship outdated versions. It is **strongly recommended** to use the [Flatpak](#flatpak) or [AppImage](#appimage) instead.

---

#### Libqt6pas
The `libqt6pas` package is not available in some distributions’ official repositories.  
You can get it from [David Bannon’s repository](https://github.com/davidbannon/libqt6pas/releases):

Ubuntu example:
```bash
sudo apt-get update
wget https://github.com/davidbannon/libqt6pas/releases/download/v6.2.8/libqt6pas6_6.2.8-1_amd64.deb
sudo dpkg -i libqt6pas6_6.2.8-1_amd64.deb
```

## Tarball

1. Download the latest tarball from the [Releases page](https://github.com/benjamimgois/Goverlay/releases).
2. Extract it:
   ```bash
   tar -xvf Goverlay*.tar.xz
   ```
3. Run the binary:
   ```bash
   ./Goverlay
   ```

> **Note:** Since version 0.6.4, MangoHud must be installed to run Goverlay.

## Building from Source

### Prerequisites

- [Lazarus IDE](https://gitlab.com/freepascal.org/lazarus/lazarus) with Qt6 widgetset support
- Qt6 development libraries (`qt6-base-dev` or equivalent)
- `make`
- `git`

### Building

```bash
git clone https://github.com/benjamimgois/Goverlay.git
cd Goverlay
make
```

This compiles both `goverlay` and the integrated `pascube` Vulkan preview.

### Running

```bash
./goverlay
```

### Installing

```bash
sudo make install
```

This installs the startup script to `/usr/local/bin/goverlay`, allowing you to launch it directly via:

```bash
goverlay
```

---

## Architecture

| Component | Technology |
|---|---|
| Language | Free Pascal (ObjFPC mode) |
| IDE / Framework | Lazarus LCL with Qt6 widgetset |
| UI Designer | Lazarus IDE manages `.lfm` files |
| Build Tool | `make` (wrapper around `lazbuild`) |
| Target | Single Linux binary (`goverlay`) |
| Preview | Integrated Vulkan demo (`pascube`, PasVulkan engine) |
| Wrapper | Compiled Free Pascal binary (`bgmod`) replacing legacy bash scripts |

---

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl + S` | Save current tab configuration |
| `Ctrl + C` | Copy launch command to clipboard |
| `Ctrl + F` | Focus global search field |
| `F1` | Open "How to use FGMOD" quick guide |

---

## Credits

### FlightlessMango

Huge thanks to **FlightlessMango**, creator and maintainer of **MangoHud** — the foundation that made Goverlay possible.

- https://flightlessmango.com
- https://github.com/flightlessmango/MangoHud
- https://discord.com/invite/Gj5YmBb

### DadSchoorse

Special thanks to **DadSchoorse**, creator of **vkBasalt**, which adds post-processing effects to Vulkan.

- https://github.com/DadSchoorse/vkBasalt

### OptiScaler Team & Contributors

Goverlay integrates several components from the OptiScaler ecosystem and community-driven projects that enable upscaling, frame generation, and NVIDIA APIs on Linux.

**OptiScaler**

Core upscaling and frame-generation project for Linux.

https://github.com/optiscaler/OptiScaler

**fakenvapi**

User-space implementation of NVAPI used by OptiScaler and other tools.

https://github.com/optiscaler/fakenvapi

**Decky-Framegen (xXJSONDeruloXx)**

Pioneer project that inspired much of the OptiScaler installation logic.

https://github.com/xXJSONDeruloXx/Decky-Framegen

**fgmod (FakeMichau)**

Another important reference implementation for frame-generation utilities on Linux.

https://github.com/FakeMichau/fgmod

**DLSS-Enabler (Artur Graniszewski)**

Tooling that expands compatibility layers for DLSS and NVAPI-based features.

https://github.com/artur-graniszewski/DLSS-Enabler

### Lazarus IDE

This project was built using the [Lazarus IDE](https://www.lazarus-ide.org/).

---

## Donations

If this project has been useful to you, consider supporting its development ❤️

[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=Q5EYYEJ5NSJAU&source=url)

goverlay

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README