Lutris Gamepad UI

A simple, TV-friendly, gamepad-navigable frontend for the Lutris 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

Table of Contents

• Requirements
• Installation
  • AppImage (Recommended)
  • Arch User Repository (AUR)
• Features
• Custom Theming Guide
• Building from Source
• Configuration
  • Environment Variables
• License

Requirements

• A Linux-based operating system.
• Lutris 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.

After downloading, make the file executable and run it:

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 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:

   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:

   {
     ":root": {
       "--accent-color": "#0078d4"
     }
   }

3. Save the file. The UI will immediately update with the new color.

Building from Source

1. Clone the repository:

   git clone https://github.com/andrew-ld/lutris-gamepad-ui.git
   cd lutris-gamepad-ui

2. Install dependencies:

   npm install

3. Run in development mode:

   npm run start

4. Build the AppImage:

   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 file for details.