feat(platform): add linux support through proton

This only support linux through proton where steam is installed from the
official package (no snap, no flatpack). I've tested this implementation
in Omarchy 3.8 (x86 arch). Thanks for the following co-authors for the
submitted PR which were the base of this commit.

Closes #128
Closes #162
Closes #184

Co-authored-by: felipefl142 <felipefrl1@hotmail.com>
Co-authored-by: charlesmerritt <chazmerritt4@gmail.com>

Author: 3 people

src/balatrobot/manager.py

@@ -10,6 +10,7 @@
 
 from balatrobot.config import Config
 from balatrobot.platforms import get_launcher
+from balatrobot.platforms.base import BaseLauncher
 
 HEALTH_TIMEOUT = 30.0
 
@@ -32,6 +33,7 @@ def __init__(
         self._process: subprocess.Popen | None = None
         self._log_path: Path | None = None
         self._session_id = session_id
+        self._launcher: BaseLauncher | None = None
 
     @property
     def port(self) -> int:
@@ -84,10 +86,10 @@ async def start(self) -> None:
         self._log_path = session_dir / f"{self._config.port}.log"
 
         # Get launcher and start process
-        launcher = get_launcher(self._config.platform)
+        self._launcher = get_launcher(self._config.platform)
         print(f"Starting Balatro on port {self._config.port}...")
 
-        self._process = await launcher.start(self._config, session_dir)
+        self._process = await self._launcher.start(self._config, session_dir)
 
         # Wait for health
         print(f"Waiting for health check on {self._config.host}:{self._config.port}...")
@@ -109,6 +111,10 @@ async def stop(self) -> None:
 
         print(f"Stopping instance on port {self._config.port}...")
 
+        # Platform-specific cleanup (e.g. wineserver -k on Linux/Proton)
+        if self._launcher is not None:
+            self._launcher.cleanup(self._config)
+
         # Try graceful termination first
         process.terminate()
 

src/balatrobot/platforms/__init__.py

@@ -40,7 +40,9 @@ def get_launcher(platform: str | None = None) -> "BaseLauncher":
 
             return MacOSLauncher()
         case "linux":
-            raise NotImplementedError("Linux launcher not yet implemented")
+            from balatrobot.platforms.linux import LinuxLauncher
+
+            return LinuxLauncher()
         case "windows":
             from balatrobot.platforms.windows import WindowsLauncher
 

src/balatrobot/platforms/base.py

@@ -67,3 +67,12 @@ async def start(self, config: Config, session_dir: Path) -> subprocess.Popen:
             )
 
         return process
+
+    def cleanup(self, config: Config) -> None:
+        """Platform-specific cleanup before terminating the process.
+
+        Called by the manager before process.terminate().
+        Override in platform launchers that need special shutdown
+        (e.g. wineserver -k for Proton on Linux).
+        """
+        pass

src/balatrobot/platforms/linux.py

@@ -0,0 +1,157 @@
+"""Linux platform launcher (Steam/Proton)."""
+
+import os
+import subprocess
+from pathlib import Path
+
+from balatrobot.config import Config
+from balatrobot.platforms.base import BaseLauncher
+
+BALATRO_APP_ID = "2379780"
+
+
+def _detect_steam_root() -> Path | None:
+    """Detect the Steam installation directory."""
+    home = Path.home()
+    candidates = [
+        home / ".local/share/Steam",
+        home / ".steam/steam",
+    ]
+    for p in candidates:
+        if (p / "steamapps").is_dir():
+            return p
+    return None
+
+
+def _detect_proton_path(steam_root: Path) -> Path | None:
+    """Find the first available Proton executable."""
+    common = steam_root / "steamapps/common"
+    if not common.is_dir():
+        return None
+    for d in sorted(common.iterdir()):
+        proton = d / "proton"
+        if proton.is_file() and "proton" in d.name.lower():
+            return proton
+    return None
+
+
+def _detect_compat_data_path(steam_root: Path) -> Path | None:
+    """Detect the Steam compatibility data directory for Balatro."""
+    p = steam_root / f"steamapps/compatdata/{BALATRO_APP_ID}"
+    return p if p.is_dir() else None
+
+
+class LinuxLauncher(BaseLauncher):
+    """Linux-specific Balatro launcher via Steam/Proton."""
+
+    def validate_paths(self, config: Config) -> None:
+        """Validate paths, auto-detect Steam/Proton/Balatro paths."""
+        # Proton needs a display server to render the game window
+        if not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"):
+            raise RuntimeError(
+                "No display server found. "
+                "Set DISPLAY or WAYLAND_DISPLAY in your environment."
+            )
+
+        steam_root = _detect_steam_root()
+        if not steam_root:
+            raise RuntimeError(
+                "Steam installation not found. "
+                "Searched: ~/.local/share/Steam, ~/.steam/steam"
+            )
+
+        # Balatro game directory
+        if config.balatro_path is None:
+            candidate = steam_root / "steamapps/common/Balatro"
+            if candidate.is_dir():
+                config.balatro_path = str(candidate)
+
+        if config.balatro_path is None:
+            raise RuntimeError(
+                "Balatro game directory not found under Steam root. "
+                "Set --balatro-path or BALATROBOT_BALATRO_PATH."
+            )
+
+        balatro = Path(config.balatro_path)
+        if not balatro.is_dir() or not (balatro / "Balatro.exe").is_file():
+            raise RuntimeError(f"Balatro game directory not found: {balatro}")
+
+        # Lovely (version.dll)
+        if config.lovely_path is None:
+            candidate = balatro / "version.dll"
+            if candidate.is_file():
+                config.lovely_path = str(candidate)
+
+        if config.lovely_path is None:
+            raise RuntimeError(
+                "lovely-injector version.dll not found. "
+                "Set --lovely-path or BALATROBOT_LOVELY_PATH."
+            )
+
+        # Proton executable
+        if config.love_path is None:
+            detected = _detect_proton_path(steam_root)
+            if detected:
+                config.love_path = str(detected)
+
+        if config.love_path is None:
+            raise RuntimeError(
+                "Proton executable not found. Set --love-path or BALATROBOT_LOVE_PATH."
+            )
+
+    def build_env(self, config: Config) -> dict[str, str]:
+        """Build environment with Proton-required variables."""
+        env = os.environ.copy()
+        env["WINEDLLOVERRIDES"] = "version=n,b"
+
+        steam_root = _detect_steam_root()
+        if steam_root:
+            env["STEAM_COMPAT_CLIENT_INSTALL_PATH"] = str(steam_root)
+            compat_data = _detect_compat_data_path(steam_root)
+            if compat_data:
+                env["STEAM_COMPAT_DATA_PATH"] = str(compat_data)
+
+        env.update(config.to_env())
+        return env
+
+    def build_cmd(self, config: Config) -> list[str]:
+        """Build Linux launch command via Proton."""
+        assert config.love_path is not None
+        assert config.balatro_path is not None
+        balatro_exe = str(Path(config.balatro_path) / "Balatro.exe")
+        return [config.love_path, "run", balatro_exe]
+
+    def cleanup(self, config: Config) -> None:
+        """Shut down the Wine prefix via wineserver -k.
+
+        Proton/Wine double-forks its children away from the original
+        process group, so process.terminate() alone leaves orphans.
+        wineserver -k cleanly terminates all Wine processes and
+        closes display connections so the compositor removes windows.
+        """
+        if config.love_path is None:
+            return
+
+        # wineserver lives next to the proton script
+        proton_dir = Path(config.love_path).parent
+        wineserver = proton_dir / "files" / "bin" / "wineserver"
+        if not wineserver.is_file():
+            return
+
+        # WINEPREFIX is inside the Steam compat data directory
+        steam_root = _detect_steam_root()
+        if not steam_root:
+            return
+        compat_data = _detect_compat_data_path(steam_root)
+        if not compat_data:
+            return
+        wineprefix = compat_data / "pfx"
+        if not wineprefix.is_dir():
+            return
+
+        subprocess.run(
+            [str(wineserver), "-k"],
+            env={"WINEPREFIX": str(wineprefix)},
+            capture_output=True,
+            timeout=10,
+        )