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
• Configuration
  • Environment Variables
• First Contribution
• Building from Source
• 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).
  • GNOME or KDE (optional, for native display management).
  • ddcutil (optional, for external monitor brightness control).
  • SDL3 (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.
  • 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.

First Contribution

Here are the steps you need to follow before submitting JavaScript changes to this repository:

1. Format the changes

   npm run prettier

2. Lint the changes

   npm run lint

3. Cleanup locale files

   LUTRIS_GAMEPAD_UI_LOCALE_CLEANUP=1 npm run build:vite

Here are the steps you need to follow before submitting Python changes to this repository:

1. Format the changes

   black lutris_wrapper.py

2. Ensure compatibility with Ubuntu 24.04 and older Lutris releases

   Many users are still running Ubuntu 24.04 with the Lutris package provided by the default APT repositories, which can be significantly older than the latest upstream release. Before submitting changes, verify that any Lutris APIs, modules, or functions you use are available in these older versions as well, and add appropriate compatibility handling when necessary to avoid import or runtime errors.

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 SDL3 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_UPDATE_CHECKER	Disable the AppImage update checker.
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_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.
LUTRIS_GAMEPAD_UI_DISABLE_SUSPEND_SYSTEM	Hide the "Suspend System" option from the system menu.
LUTRIS_GAMEPAD_UI_DISABLE_SYNC_ACCOUNT	Hide the "Sync Lutris Account" option from the system menu.

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.