Project Overview

SteamMachine-DIY is a modular framework designed to configure Arch Linux for dedicated gaming. By bypassing traditional Display Managers (such as SDDM or GDM), it streamlines system setup and session management through a minimal, systemd-integrated architecture, leveraging a Python-based core to replicate the SteamOS 3 environment.

---

📍 System Requirements

• Distribution: Arch Linux / EndeavourOS (or any Arch-based rolling release).
• Graphics Stack: 100% Open Source Drivers (Mesa).
  • AMD: RADV (Mesa)
  • Intel: ANV (Mesa)
  • NVIDIA: NVK (via vulkan-nouveau / Mesa)

Important

NVK is currently in active development; users may experience varying compatibility compared to proprietary drivers.

• Display Manager: NONE. The system handles the GPU handover directly via a dedicated Systemd Service on TTY1.
• Desktop Environment: KDE Plasma 6.x (Wayland).

---

🚀 SSOT Architecture Features

1. Zero-DM & Service-Based Boot

SteamMachine-DIY eliminates the overhead and conflicts of display managers like SDDM or GDM.

• Direct DRM Access: The session manager runs as a high-priority systemd service. Gamescope gains exclusive "DRM Master" access, reducing input lag and stuttering.
• Visual Handover: The integrated notify engine provides clean visual banners during transitions, hiding raw TTY output for a seamless experience.

2. Atomic Session Management

Transitions between Gaming Mode and Desktop are handled using Atomic Write Operations and Kernel-level Monitoring:

• Resilient against corruption: State files are updated via the write_atomic protocol (temporary buffer + os.replace). This ensures the system never reads a partial or corrupted state, even after an unexpected power-off.
• Event-Driven Watchdog: Instead of high-overhead polling, the launcher uses a native proc.wait event. If a session (Gamescope or Plasma) crashes or fails to stabilize within the VALIDATION_TIMEOUT (default: 5s), the system automatically triggers a recovery boot to the Desktop environment to prevent soft-locks.
• SSoT Integration: All session states are synchronized through the next_session variable defined in the global configuration, ensuring System-wide consistency across the entire DIY stack.

3. Dynamic Parameter Mapping

The launcher removes the need for manual script editing by acting as a dynamic bridge:

• YAML Translation: The engine parses the config.yaml manifesto and automatically maps flags and variables into optimized command-line arguments (FSR, HDR, etc.) on the fly.
• Zero-Coding Tuning: Users can modify GPU behavior by editing a simple text file, without touching the Python source code.

4. The sdy Discovery Engine

The universal sdy wrapper optimizes game execution:

• Recursive Profile Search: It climbs the directory tree to find specific .yaml configurations.
• Smart Identity: Uses SteamAppId or directory names to apply per-game tweaks, environment variables, or custom wrappers (MangoHud, GameMode).

---

⚙️ Centralized Configuration

The architecture relies on a strict separation between system-wide logic and user-specific preferences:

1. System Master (SSoT) (/etc/default/steamos_diy.conf): Defines core system identity, user context, global binary paths, and log levels.
2. User Manifesto (~/.config/steamos_diy/config.yaml): The primary interface for users to define Gamescope parameters and global environment variables.

📁 Directory Structure

• Core Logic: /usr/local/lib/steamos_diy/ (Binaries and session scripts)
• User Config: ~/.config/steamos_diy/config.yaml (The "User Manifesto")
• Game Profiles: ~/.config/steamos_diy/games.d/ (Per-game overrides)
• State Control: /var/lib/steamos_diy/next_session (Atomic session tracker)

---

📦 Essential Core Packages

• 🚀 Gamescope: Valve's micro-compositor for Wayland.
• 🎮 Steam: Running in -gamepadui mode.
• 📊 MangoHud: Vulkan/OpenGL performance overlay.
• ⚡ GameMode: Feral Interactive’s system optimizer.
• 🖥️ PyQt6: Powers the Control Center dashboard.

---

➕ Optional Packages

• Goverlay: Graphical interface for MangoHud and vkBasalt.
• LACT: Control your AMD, Nvidia, or Intel GPU.
• Bottles: Run Windows software and games.
• ProtonUp-Qt: Manage Proton-GE and Wine-GE versions.
• Lutris: Central interface for all your game libraries.

---

🎯 Philosophy: KISS (Keep It Simple, Stupid)

The project isolates all its logic within /usr/local/lib/steamos_diy/. It does not pollute standard system directories, making maintenance straightforward and removal clean. Every component communicates via standard signals and atomic state files, ensuring the system remains "power-loss resilient."

---

⬅️ Back to Home.