https://github.com/andrew-ld/lutris-gamepad-ui
A simple, TV-friendly, gamepad-navigable frontend for the Lutris game launcher on Linux.
https://github.com/andrew-ld/lutris-gamepad-ui
gamepad linuxgaming lutris
Last synced: about 2 months ago
JSON representation
A simple, TV-friendly, gamepad-navigable frontend for the Lutris game launcher on Linux.
- Host: GitHub
- URL: https://github.com/andrew-ld/lutris-gamepad-ui
- Owner: andrew-ld
- License: gpl-3.0
- Created: 2025-06-18T18:15:52.000Z (12 months ago)
- Default Branch: master
- Last Pushed: 2026-04-11T17:30:45.000Z (2 months ago)
- Last Synced: 2026-04-11T18:23:36.817Z (2 months ago)
- Topics: gamepad, linuxgaming, lutris
- Language: JavaScript
- Homepage:
- Size: 2.63 MB
- Stars: 47
- Watchers: 0
- Forks: 6
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Lutris Gamepad UI
A simple, TV-friendly, gamepad-navigable frontend for the [Lutris](https://lutris.net/) game launcher on Linux. This application provides a "10-foot UI" designed for couch gaming, allowing you to browse and launch your Lutris library entirely with a gamepad.
[View Screenshots](./README_SCREENSHOTS.md)
## Table of Contents
- [Requirements](#requirements)
- [Installation](#installation)
- [AppImage (Recommended)](#appimage-recommended)
- [Arch User Repository (AUR)](#arch-user-repository-aur)
- [Features](#features)
- [Custom Theming Guide](#custom-theming-guide)
- [Building from Source](#building-from-source)
- [Configuration](#configuration)
- [Environment Variables](#environment-variables)
- [License](#license)
## Requirements
- A Linux-based operating system.
- [Lutris](https://lutris.net/downloads) installed and configured with your games.
- For full functionality, a standard desktop environment with:
- **PulseAudio** or **PipeWire** (optional, for audio control).
- **BlueZ** (optional, for Bluetooth management).
- **GNOME** or **KDE** (optional, for native display management).
- **ddcutil** (optional, for external monitor brightness control).
- **SDL2** (optional, for LUTRIS_GAMEPAD_UI_ENABLE_SDL_INPUT).
- **X11** (optional, for Gamescope focus management).
## Installation
### AppImage (Recommended)
You can download the latest `.AppImage` from the [**Releases page**](https://github.com/andrew-ld/lutris-gamepad-ui/releases).
After downloading, make the file executable and run it:
```bash
chmod +x lutris-gamepad-ui-*.AppImage
./lutris-gamepad-ui-*.AppImage
```
### Arch User Repository (AUR)
Arch Linux users (and users of Arch-based distributions) can install [`lutris-gamepad-ui-git`](https://aur.archlinux.org/packages/lutris-gamepad-ui-git) from the AUR.
## Features
- **Gamepad-First Interface:** Navigate the entire application without a mouse or keyboard. The UI provides context-aware on-screen button prompts that adapt to your connected controller (Xbox, PlayStation, etc.) and offers audio feedback for interactions.
- **Organized Game Library:** Games are automatically organized into shelves for "Recently Played," "All Games," and by categories defined in Lutris. Find games quickly using the universal search with an integrated **on-screen keyboard**. Game cards display cover art, playtime, and last played date, with dynamically generated gradients as fallbacks for missing art.
- **Seamless Gameplay:** Launch games directly from the library. While a game is running, a clean "Now Playing" screen is displayed. Features include an **experimental pause function** and the ability to open the main Lutris desktop app directly. A global shortcut (Gamepad Home/Guide button or `Ctrl+X`) allows you to toggle the UI's visibility without closing your game.
- **Integrated System Controls:** Access a comprehensive system menu to manage your device:
- **Audio Settings:** Manage volume and switch between output devices.
- **Bluetooth Management:** Connect and disconnect devices (controllers, headsets, etc.).
- **Display Settings:** Control **Brightness** and toggle **Night Light** (supports GNOME, KDE, and external monitors via `ddcutil`).
- **Power Options:** Reboot or shutdown the system directly from the UI.
- **Customization & Localization:**
- **Multi-language Support:** Currently available in English, Italian, Persian, and Swedish.
- **Advanced Settings:** Fine-tune your experience with settings for gamepad autorepeat delay, UI zoom level, and sound feedback.
- **Theming:** Fully customizable appearance via `theme.json` (see the Custom Theming Guide below).
## Custom Theming Guide
You can customize the application's appearance by creating a `theme.json` file to override default CSS properties.
#### How It Works
On first launch, the application creates two files in its configuration directory:
- `theme.default.json`: A reference file containing all available CSS selectors and their default properties. **Do not edit this file**, as it may be overwritten by updates.
- `theme.json`: An empty file for your custom overrides.
#### Steps to Create a Custom Theme
1. **Locate the Theme Files:**
Navigate to the application's configuration directory:
```bash
cd ~/.local/lutris-gamepad-ui/
```
2. **Identify the Element to Style:**
Open `theme.default.json` to find the CSS selector for the UI element you wish to change (e.g., `:root`, `.game-card`).
3. **Add Your Overrides:**
Open `theme.json` and add your custom styles, including only the selectors and properties you wish to modify.
4. **Apply Changes:**
Save the `theme.json` file. The application will detect the changes and apply your theme instantly, no restart required.
#### Example: Changing the Accent Color
To change the main accent color from red to blue:
1. Find the `--accent-color` variable under the `:root` selector in `theme.default.json`.
2. Add the following override to your `theme.json` file:
```json
{
":root": {
"--accent-color": "#0078d4"
}
}
```
3. Save the file. The UI will immediately update with the new color.
## Building from Source
1. **Clone the repository:**
```bash
git clone https://github.com/andrew-ld/lutris-gamepad-ui.git
cd lutris-gamepad-ui
```
2. **Install dependencies:**
```bash
npm install
```
3. **Run in development mode:**
```bash
npm run start
```
4. **Build the AppImage:**
```bash
npm run build
```
## Configuration
### Environment Variables
You can customize the application's behavior using the following environment variables. Set them to `1` to enable/disable the respective feature.
| Variable | Description |
| :--------------------------------------------- | :------------------------------------------------------------------- |
| `LUTRIS_GAMEPAD_UI_IS_DEV` | Enable development mode (hot reloading, devtools). |
| `LUTRIS_GAMEPAD_UI_FORCE_WINDOWED` | Force the application to run in a window instead of fullscreen. |
| `LUTRIS_GAMEPAD_UI_LOCALE_CLEANUP` | Remove unused translation strings during build. |
| `LUTRIS_GAMEPAD_UI_ENABLE_SDL_INPUT` | Use SDL2 for gamepad input (alternative to Web Gamepad API). |
| `LUTRIS_GAMEPAD_UI_DISABLE_ANIMATIONS` | Disable all UI animations for a faster feel or lower resource usage. |
| `LUTRIS_GAMEPAD_UI_DISABLE_LUTRIS_SETTINGS` | Hide the "Lutris settings" from the system menu. |
| `LUTRIS_GAMEPAD_UI_DISABLE_AUDIO_SETTINGS` | Hide the "Audio settings" from the system menu. |
| `LUTRIS_GAMEPAD_UI_DISABLE_DISPLAY_SETTINGS` | Hide the "Display settings" from the system menu. |
| `LUTRIS_GAMEPAD_UI_DISABLE_BLUETOOTH_SETTINGS` | Hide the "Bluetooth settings" from the system menu. |
| `LUTRIS_GAMEPAD_UI_DISABLE_OPEN_LUTRIS` | Hide the "Open Lutris" option from the system menu. |
| `LUTRIS_GAMEPAD_UI_DISABLE_REBOOT_SYSTEM` | Hide the "Reboot System" option from the system menu. |
| `LUTRIS_GAMEPAD_UI_DISABLE_POWER_OFF_SYSTEM` | Hide the "Power Off System" option from the system menu. |
| `LUTRIS_GAMEPAD_UI_DISABLE_BUG_REPORT` | Hide the "Generate Bug Report" option from the system menu. |
## License
This project is licensed under the **GNU General Public License v3.0**. See the [LICENSE](LICENSE) file for details.