a-la-karte/README.md

# A-La-Karte

[![KDE Frameworks 6](https://img.shields.io/badge/KDE%20Frameworks-6-blue)](https://develop.kde.org/frameworks/)
[![Qt 6](https://img.shields.io/badge/Qt-6.6+-green)](https://www.qt.io/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

A unified game launcher for KDE Plasma 6, inspired by [KDE Apps Initiative issue#26](https://invent.kde.org/teams/apps-initiative/tasks/-/issues/26).

## Features

- Import games from Steam, Lutris, Heroic, Bottles, itch.io, Legendary, RetroArch playlists, Flatpak applications, and desktop entries
- Manual game entries with editable metadata (name, developer/publisher, executable, working directory)
- Per-game launch overrides (environment variables, compatibility runner selection, Wine/Proton prefix path)
- Per-game screenshots gallery with import and centralized storage
- Grid and list views
- Search by name/developer/publisher and filter by source
- Favorites and hidden games views
- Last-played timestamp
- Optional SteamGridDB cover fetching (requires API key)
- Optional KRunner integration (if KF6Runner is available at build time)
- Gamepad navigation (via SDL3)

## Requirements

### Build Dependencies

- CMake >= 3.20
- Qt >= 6.6
- KDE Frameworks >= 6.0
  - Kirigami
  - KI18n
  - KCoreAddons
  - KConfig
- Extra CMake Modules (ECM)
- SDL3

### Runtime Dependencies

- Qt 6 (Core, Quick, QuickControls2, Gui, Network, Concurrent)
- Kirigami 6
- KDE Frameworks 6

### Optional

- Steam (for Steam game import)
- Lutris (for Lutris game import)
- Heroic Games Launcher (for Epic/GOG/Amazon game import)
- Bottles (for Windows apps via Wine)
- itch.io app (for itch.io games)
- Legendary CLI (for Epic Games)
- RetroArch (for retro games via playlists)

## Building

### Using kde-builder (Recommended)

This project is not currently part of KDE's repo-metadata, so you need to add it as a custom project in your `~/.config/kde-builder.yaml`.

1. Set up kde-builder:
   - https://develop.kde.org/docs/getting-started/building/kde-builder-setup/
2. Install distro build dependencies:

```bash
kde-builder --install-distro-packages
```

3. Add a project entry to `~/.config/kde-builder.yaml`:

```yaml
project alakarte:
  repository: https://invent.kde.org/marcoa/a-la-karte.git
  cmake-options: -DALAKARTE_SDL3_SOURCE_DIR=/path/to/SDL
```

4. Build:

```bash
kde-builder alakarte
```

To run the built app:

```bash
kde-builder --run alakarte
```

### Manual Build

```bash
cmake -B build -S . -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build
cmake --install build
```

### Development Build

```bash
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
cmake --build build
./build/bin/alakarte
```

## Usage

1. Launch A-La-Karte from your application menu or run `alakarte`
2. If your library is empty, the import dialog opens automatically
3. Import games from your supported platforms
4. Your games will appear in the library grid
5. Select a game to see details, double-click or press Play to launch

### Keyboard Shortcuts

- **Ctrl+F**: Focus search field
- **Ctrl+N**: Add new game
- **Ctrl+I**: Open import dialog
- **Ctrl+,**: Open settings
- **Ctrl+H**: Toggle hidden games view
- **Ctrl+D**: Show game details
- **F5**: Refresh/import all games
- **Escape**: Close dialog/sheet or clear search
- **Enter/Space**: Select/launch game in grid

### Gamepad Controls

- **D-pad / Left Stick**: Navigate grid
- **A Button**: Select/launch game
- **B Button**: Back/close dialog
- **Start**: Open settings
- **Y Button**: Focus search

## Supported Platforms

### Steam

A-La-Karte automatically detects Steam installations at:
- `~/.steam/steam`
- `~/.local/share/Steam`
- Flatpak: `~/.var/app/com.valvesoftware.Steam/.local/share/Steam`

All library folders are scanned for installed games.

### Lutris

Games are imported from:
- `~/.local/share/lutris`
- Flatpak: `~/.var/app/net.lutris.Lutris/data/lutris`

Uses the Lutris CLI when available for best results.

### Heroic Games Launcher

Supports Epic Games, GOG, and Amazon Games via Heroic:
- `~/.config/heroic`
- Flatpak: `~/.var/app/com.heroicgameslauncher.hgl/config/heroic`

### Bottles

Windows applications via Wine:
- `~/.local/share/bottles`
- Flatpak: `~/.var/app/com.usebottles.bottles/data/bottles`

### itch.io

Games installed via the itch.io app:
- `~/.config/itch/db/butler.db`
- Flatpak: `~/.var/app/io.itch.itch/config/itch/db/butler.db`

### Legendary

Epic Games via Legendary CLI:
- `~/.config/legendary`

### RetroArch

Retro games from RetroArch playlists:
- `~/.config/retroarch/playlists`
- Flatpak: `~/.var/app/org.libretro.RetroArch/config/retroarch/playlists`

### Desktop Entries

Games from XDG .desktop files in standard application directories.

### Flatpak Games

Games installed as Flatpak applications (detected by category).

## Configuration

Settings are stored in `~/.config/alakarterc` and include:

- View mode (Grid/List)
- Grid size
- Platform badge visibility
- Auto-import on startup
- Enabled import sources

Game library is stored in `~/.local/share/alakarte/library.json`.

Imported screenshots are stored under `~/.local/share/alakarte/media/screenshots/<gameId>/`.

## Code Overview

- **Application entry point**: `src/main.cpp`
- **Core singleton**: `src/app.*` exposes models/services to QML (game model, launcher, config, SteamGridDB)
- **Data model**:
  - `src/game.*` stores per-game metadata
  - `src/gamemodel.*` and `src/gamesortfiltermodel.*` provide sorting/filtering for the UI
- **Media**: `src/mediamanager.*` + `src/screenshotmodel.*` provide centralized per-game screenshot management
- **Importers**: `src/*importer.*` (Steam/Lutris/Heroic/etc.)
- **Launcher**: `src/gamelauncher.*` launches processes/URLs and records last-played on launch
- **UI**: `src/qml/` (Kirigami + Qt Quick)

## Local Smoke Testing (Repeatable)

If you want to test without affecting your real configuration/library, run with isolated XDG directories:

```bash
export XDG_CONFIG_HOME="$(mktemp -d)"
export XDG_DATA_HOME="$(mktemp -d)"
./build/bin/alakarte
```

Suggested quick checks:

1. Add a manual entry with a harmless command (e.g. `true` or `sleep 2`) and launch it.
2. Confirm `Last played` updates after launch.
3. Toggle favorite/hidden and confirm filtering works.
4. Open the import sheet and run an import; confirm it completes and does not crash even if sources are missing.
5. (Optional) Create a temporary `.desktop` file under `$XDG_DATA_HOME/applications/` and verify the Desktop Entries importer detects it.

## Contributing

Contributions are welcome! Please see the [KDE development guidelines](https://community.kde.org/Get_Involved/development).

### Getting Started

1. Set up your development environment: https://develop.kde.org/docs/getting-started/building/kde-builder-setup/
2. Clone the repository
3. Build and test your changes
4. Submit a merge request

### Code Style

This project follows KDE coding conventions:
- https://community.kde.org/Policies/Frameworks_Coding_Style
- https://community.kde.org/Policies/Library_Code_Policy

## License

A-La-Karte is licensed under the GNU General Public License v3.0 or later.

See [LICENSES/GPL-3.0-or-later.txt](LICENSES/GPL-3.0-or-later.txt) for the full license text.

## Links

- [KDE API Documentation](https://api.kde.org/)
- [Kirigami Documentation](https://develop.kde.org/frameworks/kirigami/)
- [KDE Development Guidelines](https://community.kde.org/Get_Involved/development)
- [Project Repository](https://invent.kde.org/marcoa/a-la-karte)
- [Issue Tracker](https://invent.kde.org/marcoa/a-la-karte/-/issues)