debianito-post-install/docs/gaming.md

## Option 7: Gaming Ecosystem, Performance Tweaks & Runtimes

### 1. Philosophy of the Gaming Environment in Debian

The Debianito gaming module transforms a server-grade Debian installation into a dedicated gaming station by carefully isolating dependencies and configuring compatibility layers without compromising system stability. The core philosophy follows three principles:

**Dependency Isolation:** All gaming-specific packages (Steam, Heroic, Mesa 32-bit libraries) are installed in user-space where possible, preventing conflicts with base system packages. The `steam-installer` package from Debian's contrib section is used as the bootstrap mechanism rather than Valve's official repository for stability reasons—this ensures compatibility with Debian's package management and reduces update complexity.

**Compatibility Layer Configuration:** Proton/Wine support is enabled through automatic installation of required 32-bit libraries (`libgl1-mesa-dri:i386`, `mesa-vulkan-drivers:i386`) that are mandatory for running Windows-only games on Linux. The module detects GPU architecture and installs appropriate drivers (NVIDIA proprietary, AMD open-source, Intel built-in) before attempting any launcher installation.

**Stability Over Features:** Unlike gaming-focused distributions that prioritize bleeding-edge kernels or unstable repositories, Debianito maintains the stability of Debian Stable while providing necessary backports for Mesa 32-bit support when available. This ensures long-term compatibility with games and launchers without risking system breakage from aggressive updates.

The module architecture separates concerns into distinct scripts (`steam.sh`, `heroic.sh`, `tools.sh`) that can be sourced independently, allowing users to enable only the components they need while maintaining a clean, auditable installation history.

---

### 2. Launchers and Compatibility Layers (Steam & Heroic)

**Steam Installation Logic:** The `install_steam()` function in `steam.sh` leverages Debian's native package management through the `apt install -y steam-installer` command. This approach differs from Valve's official repository for several reasons:

1. **32-bit Architecture Requirement:** Steam requires 32-bit libraries to run modern Windows games via Proton. The script explicitly prompts users to enable Multi-Arch support (`dpkg --add-architecture i386`) and install the complete Mesa stack for both amd64 and i386 architectures:
   ```bash
   apt install mesa-vulkan-drivers libglx-mesa0:i386 mesa-vulkan-drivers:i386 \
              libgl1-mesa-dri:i386 libegl-mesa0:i386 mesa-va-drivers:i386
   ```

2. **Runtime Dependency Chain:** The `steam-installer` package depends on several critical components:
   - `debconf` and `cdebconf` for configuration management
   - `default-dbus-session-bus` for inter-process communication
   - `lsof` for file listing utilities
   - `zenity` or `yad` for graphical dialogs
   - `steam-libs` and `steam-libs-i386` metapackages

3. **Self-Update Mechanism:** The installed Steam launcher includes a minimal version capable of downloading full updates automatically, reducing manual intervention requirements.

**Heroic Games Launcher Management:** Unlike Steam's Debian package approach, Heroic requires direct download from GitHub releases due to its rapid iteration cycle. The `install_heroic()` function in `heroic.sh` implements:

1. **Release Detection:** Uses GitHub API to identify the latest amd64 `.deb` release dynamically
2. **Dependency Pre-installation:** Ensures `curl` and `wget` are available before attempting download
3. **Temporary File Handling:** Downloads to `/tmp/heroic.deb`, validates file integrity, then installs via apt

```bash
gh_url=$(curl -s --connect-timeout 10 https://api.github.com/repos/Heroic-Games-Launcher/\
HeroicGamesLauncher/releases/latest | \
    grep -oP 'https://[^"]+amd64\.deb' | head -1)
```

This approach ensures users always get the latest stable release while maintaining compatibility with Debian's package verification mechanisms. The script also supports Flatpak alternatives for users who prefer sandboxed installations through Flathub.

---

### 3. Optimization Engine and Telemetry (GameMode & MangoHud)

**Feral GameMode Daemon:** When a game launches with `gamemoderun`, the Feral GameMode daemon performs several critical optimizations at the kernel level:

1. **CPU Scheduler Priority:** Adjusts scheduling policies to prioritize gaming processes over background tasks, reducing latency spikes during gameplay
2. **I/O Priority Management:** Increases I/O priority for game processes while deprioritizing non-essential system operations (updates, backups)
3. **Kernel Governor Tuning:** Forces CPU governor to Performance mode when games are detected, eliminating frequency scaling delays
4. **Screensaver Inhibition:** Prevents screensavers from activating during gaming sessions

The `install_gamemode()` function in `tools.sh` ensures the daemon is available system-wide:
```bash
_run_install gamemode
```

This allows users to wrap game launch commands with `gamemoderun %command%` for automatic optimization without manual configuration.

**MangoHud + goverlay Integration:** MangoHud provides real-time performance telemetry through Vulkan/OpenGL overlays that render directly into the game window:

1. **FPS Counter:** Displays current and average frames per second
2. **Temperature Monitoring:** Tracks CPU/GPU temperatures in real-time
3. **Memory Usage:** Shows VRAM, RAM, and swap utilization metrics
4. **Native Rendering:** Uses Vulkan/OpenGL hooks for efficient overlay rendering without impacting game performance

The `install_mangohud()` function handles both 64-bit and 32-bit installations:
```bash
if dpkg --print-foreign-architectures | grep -q i386; then
    echo "Installing 32-bit MangoHud..."
    _run_cmd "MangoHud" "sudo apt install -y mangohud:i386"
fi
```

The `goverlay` component extends this functionality by integrating with Wayland compositors for smoother overlay behavior on modern desktop environments. Both tools work together to provide comprehensive performance visibility without requiring game-specific configuration.

---

### 4. Peripheral Control and RGB Lighting (OpenRGB)

**Secure Hardware Access:** OpenRGB requires direct communication with hardware peripherals through the I2C bus, which traditionally required root privileges. The `install_openrgb()` function implements several security measures:

1. **udev Rule Configuration:** Reloads udev rules to properly identify and manage I2C devices without requiring elevated permissions during runtime
2. **Module Loading:** Ensures `i2c-dev` module is loaded and added to `/etc/modules` for persistence across reboots
3. **Group Membership:** Adds the user to the `i2c` group via `usermod -aG i2c "$USER"` so OpenRGB can access hardware without root
4. **Capability Assignment:** Sets raw I/O capabilities on the binary using `setcap cap_sys_rawio=ep /usr/bin/openrgb`, allowing direct hardware communication while maintaining user-space execution

The script includes version-specific download URLs for Debian Bookworm (12) and Trixie (13), ensuring compatibility with different kernel versions:
```bash
if [ "$DEBIAN_VERSION" = "12" ]; then
    url="https://codeberg.org/OpenRGB/OpenRGB/releases/download/release_candidate_1.0rc2/openrgb_1.0rc2_amd64_bookworm_0fca93e.deb"
elif [ "$DEBIAN_VERSION" = "13" ]; then
    url="https://codeberg.org/OpenRGB/OpenRGB/releases/download/release_candidate_1.0rc2/openrgb_1.0rc2_amd64_trixie_0fca93e.deb"
fi
```

This approach eliminates the security risk of running OpenRGB as root while maintaining full hardware control for RGB peripherals, RAM modules, and motherboard lighting systems. Users must log out/in or reboot after installation to apply group membership changes.

---

### 5. Java Runtimes (Eclipse Temurin 8 / 17 / 21)

**Multi-Version Support:** The gaming module provides three specific Eclipse Temurin versions to accommodate different game requirements:

| Version | Use Case | Justification |
|---------|----------|---------------|
| **Temurin 8** | Legacy Minecraft mods, older Java games | Maintains compatibility with mods written for Java 8 (2014-2019 era) |
| **Temurin 17** | Modern Minecraft servers, newer game clients | Balances performance and compatibility for post-1.16+ game versions |
| **Temurin 21** | Latest game engines, cutting-edge mods | Provides best performance for modern Java applications |

The script injects the official Adoptium repository to pull community-maintained builds rather than Oracle's proprietary JRE:
```bash
# Repository injection logic (simplified)
echo "deb [signed-by=/etc/apt/keyrings/adoptium.asc] https://packages.adoptium.net/artifactory/deb $(awk -F= '/^VERSION_CODENAME/{print$2}' /etc/os-release) main" | sudo tee /etc/apt/sources.list.d/adoptium.list
```

**Version Selection Logic:** Users can choose which Temurin version to install based on their specific game requirements. The module justifies offering all three versions because:

1. **Backward Compatibility:** Java 8 remains in use by many Minecraft mods and older game clients that haven't been updated for newer JVMs
2. **Performance Optimization:** Java 21 provides the best performance characteristics for modern games with heavy multithreading requirements
3. **Security Updates:** All Temurin versions receive regular security patches from the Eclipse Foundation community

The installation process ensures clean repository management without polluting the system with multiple conflicting JRE installations, maintaining Debian's package integrity while providing flexibility for different gaming scenarios.