Project Overview

SteamMachine-DIY is a lightweight, modular framework designed to transform any Arch Linux-based distribution into a high-performance gaming console, providing an experience identical to SteamOS 3 (Steam Deck).

Unlike other solutions, SteamMachine-DIY does not rely on a traditional Display Manager (like SDDM or GDM). Instead, it manages the session lifecycle directly through systemd and a logic core written entirely in Python.

---

📍 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)
• 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:

• Corruption Proof: 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.
• Kernel-Level 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 absolute 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.