Feature: Wrapper, Logging und Doku überarbeitet

- Debug-Logging optional gemacht, den Legacy-Wrapper portabler aufgebaut (relative Pfade, Debug-Weitergabe, Python-Fallback) und die README für Endanwender und Entwickler klarer neu strukturiert.
2026-11-15 09:33:14 +01:00 · 2026-04-18 17:10:23 +02:00
parent a00bd1ed30
commit d91735a2fa
5 changed files with 242 additions and 94 deletions
@@ -6,11 +6,15 @@ Windows-Hilfsprogramm, das ein Spielfenster automatisch in den Vordergrund bring

 ## Inhaltsverzeichnis

+- [Schnellstart](#schnellstart)
+  - [Für Nutzer](#fur-nutzer)
+  - [Für Entwickler](#fur-entwickler)
 - [Problembeschreibung](#problembeschreibung)
 - [Lösungsansatz](#lösungsansatz)
 - [Architektur](#architektur)
 - [Voraussetzungen](#voraussetzungen)
- [Installation](#installation)
+- [Direkte Verwendung](#direkte-verwendung)
+- [Aus Quellcode ausführen](#aus-quellcode-ausfuhren)
 - [Konfiguration](#konfiguration)
  - [Steam](#steam)
  - [Sunshine / Moonlight](#sunshine--moonlight)
@@ -29,6 +33,47 @@ Windows-Hilfsprogramm, das ein Spielfenster automatisch in den Vordergrund bring

 ---

+## Schnellstart
+
+### Für Nutzer
+
+Wenn du FocusFix direkt verwenden willst, ist eine fertige `FocusFix.exe` der empfohlene Weg. Du brauchst dann weder ein Virtual Environment noch ein manuelles `pip install`.
+
+Steam-Beispiel:
+
+```text
+"C:\Path\To\FocusFix\FocusFix.exe" %command%
+```
+
+Mit Debug-Logging:
+
+```text
+"C:\Path\To\FocusFix\FocusFix.exe" -debug %command%
+```
+
+### Für Entwickler
+
+Wenn du FocusFix aus dem Repository starten oder weiterentwickeln willst:
+
+```bash
+cd C:\Path\To\FocusFix
+py -m pip install -r requirements.txt
+```
+
+Danach kannst du `focusfix.py` direkt mit deinem Python-Interpreter oder über `pythonw.exe` verwenden.
+
+Steam-Beispiel für die Quellcode-Nutzung mit lokalem `.venv`:
+
+```text
+"C:\Projekte\FocusFix\.venv\Scripts\pythonw.exe" "C:\Projekte\FocusFix\focusfix.py" %command%
+```
+
+Ohne lokales `.venv` und mit globalem Python im `PATH`:
+
+```text
+"pythonw.exe" "C:\Projekte\FocusFix\focusfix.py" %command%
+```
+
 ## Problembeschreibung

 Beim Start eines Spiels über Steam oder Sunshine/Moonlight öffnet sich das Spielfenster im **Hintergrund**. Die Steam-Oberfläche, die Windows-Taskleiste oder andere Fenster verdecken es, und der Spieler muss manuell per Alt+Tab wechseln.
@@ -86,33 +131,31 @@ Steam Launch Options / Sunshine Befehlsvorbereitung
 | Komponente | Version | Hinweis |
 |---|---|---|
 | Windows | 10 / 11 | Benötigt Win32 API (user32.dll) |
-| Python | 3.10+ | `py` Launcher muss verfügbar sein |
-| pip-Pakete | `psutil`, `pywin32` | Werden im `.venv` installiert |
 | Steam | Beliebig | Startoptionen müssen konfigurierbar sein |
+| Python | 3.10+ | Nur für Quellcode-Nutzung erforderlich |
+| pip-Pakete | `psutil`, `pywin32` | Nur für Quellcode-Nutzung erforderlich |

-## Installation
+## Direkte Verwendung
+
+Für normale Nutzer ist eine fertige `.exe` der einfachste Weg.
+
+## Aus Quellcode ausführen

 ```bash
 cd C:\Path\To\FocusFix
-
-# Virtual Environment erstellen
-py -m venv .venv
-
-# Aktivieren
-.venv\Scripts\activate
-
-# Abhängigkeiten installieren
-pip install psutil pywin32
+py -m pip install -r requirements.txt
 ```

-### Dateistruktur nach Installation
+Optional kannst du dafür auch ein Virtual Environment verwenden. Für Entwickler ist das sinnvoll, für Endanwender aber nicht der Standardweg.
+
+### Dateistruktur im Repository

 ```
 C:\Path\To\FocusFix\
-├── .venv\                  # Python Virtual Environment
 ├── focusfix.py             # Hauptscript
-├── focusfix.log            # Logdatei (wird automatisch erstellt)
+├── focusfix.log            # Logdatei (nur bei --debug / -debug)
 ├── launch.vbs              # Legacy-Wrapper, optional
+├── requirements.txt        # Python-Abhängigkeiten für Quellcode-Nutzung
 ├── CLAUDE.md               # Kontext für Claude Code
 └── README.md               # Diese Dokumentation
 ```
@@ -125,10 +168,25 @@ C:\Path\To\FocusFix\
 2. Rechtsklick auf das Spiel → **Eigenschaften**
 3. Unter **Allgemein → Startoptionen** eine der folgenden Varianten eintragen:

-#### Variante A — Empfohlen: direkt mit `focusfix.py`
+#### Variante A — Empfohlen für Nutzer: `FocusFix.exe`

 ```text
-"C:\Path\To\FocusFix\.venv\Scripts\pythonw.exe" "C:\Path\To\FocusFix\focusfix.py" %command%
+"C:\Path\To\FocusFix\FocusFix.exe" %command%
+```
+
+Mit Debug-Logging:
+
+```text
+"C:\Path\To\FocusFix\FocusFix.exe" -debug %command%
+```
+
+Die `.exe` übernimmt denselben Wrapper-Modus wie `focusfix.py`: Sie erhält `%command%`, startet das Spiel und überwacht danach den Fokus. Diese Variante ist für Endanwender gedacht.
+Die Pfade im Beispiel sind Platzhalter und müssen durch deinen tatsächlichen Installationspfad ersetzt werden.
+
+#### Variante B — Quellcode direkt mit `focusfix.py`
+
+```text
+"C:\Path\To\Python\pythonw.exe" "C:\Path\To\FocusFix\focusfix.py" %command%
 ```

 `focusfix.py` extrahiert den Prozessnamen automatisch aus `%command%`, startet das eigentliche Spiel und überwacht danach den Fensterfokus. Die gleiche Startoption kann für beliebige Steam-Spiele mit vergleichbarem Fokus-Problem verwendet werden.
@@ -139,41 +197,49 @@ Die Pfade im Beispiel sind Platzhalter und müssen durch deinen tatsächlichen I
 - `"...\focusfix.py"` — Python-Script im Steam-Wrapper-Modus
 - `%command%` — Steam-Platzhalter, wird zur Laufzeit durch den vollständigen Pfad zur Spiel-Executable ersetzt, z.B. `"C:\SteamLibrary\...\Game.exe"`

-#### Variante B — Legacy: über `launch.vbs`
+#### Variante C — Legacy: über `launch.vbs`

 Wenn du den alten VBScript-Wrapper weiterhin verwenden willst, kannst du in Steam Folgendes eintragen:

 ```text
 wscript "C:\Path\To\FocusFix\launch.vbs" %command%
+Beispiel: "C:\Projekte\FocusFix\launch.vbs" %command%
 ```

-`launch.vbs` extrahiert den Prozessnamen aus `%command%`, startet `focusfix.py` unsichtbar mit `--process` und startet danach das eigentliche Spiel. Diese Variante funktioniert weiterhin, ist aber nur noch als Legacy-/Fallback-Weg gedacht, weil `focusfix.py` den Wrapper-Job inzwischen selbst übernehmen kann.
-Die Pfade im Beispiel sind Platzhalter und müssen durch deinen tatsächlichen Installationspfad ersetzt werden.
+Mit Debug-Logging:
+
+```text
+wscript "C:\Path\To\FocusFix\launch.vbs" -debug %command%
+wscript "C:\Projekte\FocusFix\launch.vbs" -debug %command%
+```
+
+`launch.vbs` extrahiert den Prozessnamen aus `%command%`, startet `focusfix.py` unsichtbar mit `--process` und startet danach das eigentliche Spiel. `-d`, `-debug` und `--debug` werden an `focusfix.py` weitergereicht und nicht an das Spiel übergeben. Diese Variante funktioniert weiterhin, ist aber nur noch als Legacy-/Fallback-Weg gedacht, weil `focusfix.py` den Wrapper-Job inzwischen selbst übernehmen kann.
+Der Wrapper erwartet `focusfix.py` relativ zu seinem eigenen Speicherort. Für Python nutzt er zuerst `.venv\Scripts\pythonw.exe` im selben Ordner und fällt, falls nicht vorhanden, auf `pythonw.exe` aus der globalen Installation beziehungsweise dem `PATH` zurück.

 **Erklärung:**
 - `wscript` — startet VBScript ohne sichtbares Konsolenfenster
 - `"...\launch.vbs"` — Legacy-Wrapper, der `focusfix.py` indirekt startet
+- `-debug` — optional, aktiviert `focusfix.log` für `focusfix.py`
 - `%command%` — Steam-Platzhalter mit dem ursprünglichen Spielstartbefehl

-#### Variante C — Release-Exe
-
-Wenn du eine gebaute Release-Datei verwenden willst, kannst du statt Python direkt die `.exe` in Steam eintragen. In diesem Repository liegt aktuell eine Build-Datei unter `dist\nuinstall\FocusFix.exe`:
-
-```text
-"C:\Path\To\FocusFix\dist\nuinstall\FocusFix.exe" %command%
-```
-
-Die `.exe` übernimmt denselben Wrapper-Modus wie `focusfix.py`: Sie erhält `%command%`, startet das Spiel und überwacht danach den Fokus. Diese Variante ist praktisch, wenn du keine sichtbare Python-Installation oder kein venv in den Steam-Startoptionen referenzieren willst.
-
-**Wichtig:** Der Dateiname der Release-Exe hängt vom Build ab. Wenn du später eine neu benannte Exe wie `FocusFix.exe` baust, muss genau dieser Pfad in Steam eingetragen werden.
-Auch hier sind die Pfade im Beispiel Platzhalter und müssen durch deinen tatsächlichen Installationspfad ersetzt werden.
-
 ### Sunshine / Moonlight

-In Sunshine als **Befehlsvorbereitung** (Command Preparation) pro Spiel eintragen:
+Für Nutzer mit `.exe`:

 ```text
-"C:\Path\To\FocusFix\.venv\Scripts\pythonw.exe" "C:\Path\To\FocusFix\focusfix.py" --process "Prozessname"
+"C:\Path\To\FocusFix\FocusFix.exe" --process "Prozessname"
+```
+
+Mit Debug-Logging:
+
+```text
+"C:\Path\To\FocusFix\FocusFix.exe" --debug --process "Prozessname"
+```
+
+Für Quellcode-Nutzung in Sunshine als **Befehlsvorbereitung** (Command Preparation) pro Spiel:
+
+```text
+"C:\Path\To\Python\pythonw.exe" "C:\Path\To\FocusFix\focusfix.py" --process "Prozessname"
 ```

 Den Prozessnamen im Task-Manager ablesen, ohne `.exe`. Beispiele:
@@ -183,7 +249,7 @@ Den Prozessnamen im Task-Manager ablesen, ohne `.exe`. Beispiele:
 | Crimson Desert | `CrimsonDesert` |
 | Wuthering Waves | `Client-Win64-Shipping` |

-**Wichtig:** Der vollständige Pfad zu `pythonw.exe` im `.venv` ist nötig, damit die Abhängigkeiten (`psutil`, `pywin32`) gefunden werden. `py` oder `python` nutzt sonst möglicherweise eine andere Python-Installation.
+**Wichtig:** Wenn du den Quellcode-Weg nutzt, muss der verwendete Python-Interpreter Zugriff auf die installierten Abhängigkeiten aus `requirements.txt` haben. `pythonw.exe` ist für unsichtbare Hintergrundausführung sinnvoller als `python.exe`.

 ## Ablauf zur Laufzeit

@@ -245,7 +311,7 @@ t=~15s  Erfolg → focusfix.py beendet sich

 ### launch.vbs

-`launch.vbs` ist nur noch ein Legacy-Wrapper. Die aktuelle empfohlene Steam-Konfiguration nutzt `focusfix.py` direkt. Die Datei kann als Fallback im Repository bleiben, wird für den normalen Ablauf aber nicht mehr benötigt.
+`launch.vbs` ist nur noch ein Legacy-Wrapper. Die aktuelle empfohlene Nutzung für Endanwender erfolgt über `FocusFix.exe`. Die Datei kann als Fallback im Repository bleiben, wird für den normalen Ablauf aber nicht mehr benötigt. Der Wrapper löst `focusfix.py` relativ zu seinem eigenen Ordner auf, verwendet bevorzugt `.venv\Scripts\pythonw.exe` daneben und fällt sonst auf `pythonw.exe` aus der globalen Python-Installation beziehungsweise dem `PATH` zurück. `-d`/`-debug`/`--debug` kann er an `focusfix.py` weitergeben.

 ## Konfigurationsparameter

@@ -271,7 +337,8 @@ Es muss entweder `--process` oder ein Spielbefehl übergeben werden.

 | Pfad | Zweck |
 |---|---|
-| `C:\Path\To\FocusFix\.venv\Scripts\pythonw.exe` | Beispielpfad zum Python-Interpreter ohne Konsolenfenster, für Steam empfohlen |
+| `C:\Path\To\FocusFix\FocusFix.exe` | Empfohlener Pfad für Endanwender |
+| `C:\Path\To\Python\pythonw.exe` | Beispielpfad zum Python-Interpreter ohne Konsolenfenster, für Quellcode-Nutzung |
 | `C:\Path\To\FocusFix\focusfix.py` | Beispielpfad zum Hauptscript |

 Bei einer Änderung des Installationsverzeichnisses müssen diese Pfade in den Steam-Startoptionen oder in Sunshine angepasst werden.
@@ -312,27 +379,27 @@ Das wichtigste Unterscheidungsmerkmal ist hier die Fenstergröße. Kleine Startf

 ```bash
 cd C:\Path\To\FocusFix
-.venv\Scripts\python focusfix.py --process "CrimsonDesert" --timeout 5
+python focusfix.py --process "CrimsonDesert" --timeout 5
 ```

 ### Steam-Wrapper-Modus testen

 ```bash
-.venv\Scripts\python focusfix.py "C:\Path\To\Game\TestGame.exe"
+python focusfix.py "C:\Path\To\Game\TestGame.exe"
 ```

-Die Laufzeit-Logs landen in `focusfix.log`. Bei Ausführung über `pythonw.exe` gibt es keine sichtbare Ausgabe. Bei manuellen Starts mit `python.exe` können Argument- oder Interpreter-Fehler weiterhin in der Konsole erscheinen.
+Standardmäßig erzeugt FocusFix keine Logdatei. Mit `--debug` oder `-debug` landen die Laufzeit-Logs in `focusfix.log`; bei jedem neuen Scriptstart wird die Datei dabei überschrieben. Bei Ausführung über `pythonw.exe` gibt es keine sichtbare Ausgabe. Bei manuellen Starts mit `python.exe` können Argument- oder Interpreter-Fehler weiterhin in der Konsole erscheinen.

 ### Gesamtablauf testen

 1. Steam-Startoptionen wie oben konfigurieren.
 2. Spiel über Steam starten.
 3. Erwartung: Spielfenster erscheint nach dem Ladescreen im Vordergrund, ohne zusätzliches Konsolenfenster.
-4. `focusfix.log` prüfen.
+4. Falls mit `--debug` gestartet wurde, `focusfix.log` prüfen.

 ## Debugging

-Alle Informationen werden in `focusfix.log` protokolliert:
+Für die Fehlersuche FocusFix mit `--debug` oder `-debug` starten. Dann werden alle Informationen in `focusfix.log` protokolliert; ein vorhandenes Logfile aus einem früheren Lauf wird dabei ersetzt:

 - Gefundene Kandidaten-Fenster mit Handle, Titel, Größe und PID
 - Fensterwechsel und ignorierte titellose Fenster
@@ -343,12 +410,12 @@ Alle Informationen werden in `focusfix.log` protokolliert:

 | Symptom | Ursache | Lösung |
 |---|---|---|
-| Spiel startet nicht | Steam-Startoptionen fehlerhaft | Prüfen ob `%command%` am Ende steht und `pythonw.exe`/`focusfix.py` korrekt referenziert werden |
-| `ModuleNotFoundError: psutil` | Falsche Python-Installation | Vollständigen Pfad zu `.venv\Scripts\pythonw.exe` verwenden |
+| Spiel startet nicht | Steam-Startoptionen fehlerhaft | Prüfen ob `%command%` am Ende steht und `.exe` oder `pythonw.exe`/`focusfix.py` korrekt referenziert werden |
+| `ModuleNotFoundError: psutil` | Falsche Python-Installation | `py -m pip install -r requirements.txt` ausführen oder den richtigen Python-Interpreter verwenden |
 | Script findet Prozess nicht | Prozessname stimmt nicht oder Launcher-Kette ist ungewöhnlich | Mit `--process` testen oder Log prüfen |
 | Fenster wird nicht fokussiert | Windows-Restriktion zu streng | Retry-Anzahl/Delay in Konstanten erhöhen |
 | Alt-Taste bleibt hängen | Spiel mit Admin-Rechten, Script ohne | Script ebenfalls als Admin starten |
-| CMD-Fenster sichtbar | `python.exe` statt `pythonw.exe` | Steam-/Sunshine-Konfiguration prüfen |
+| CMD-Fenster sichtbar | `python.exe` statt `pythonw.exe` | Steam-/Sunshine-Konfiguration prüfen oder `.exe` verwenden |
 | Verdunkeltes/blockiertes Spiel | Titelloses Overlay-Fenster | Log prüfen; sollte meist durch Fenster-mit-Titel-Bevorzugung abgefangen werden |

 ### Fenster-Inspektion per PowerShell