Contributing

Configuration

@@ -1,22 +1,19 @@
-The script reads a config file from:
-	1.	~/.gaming-mode.conf (user override), or
-	2.	/etc/gaming-mode.conf (system-wide default)
+W.O.P.R. reads an optional configuration file from:
+	•	User-level (preferred): ~/.gaming-mode.conf
+	•	System-wide: /etc/gaming-mode.conf
 
-Available options
+If neither exists, sensible defaults are used.
 
-# How Steam launches:
-#   bigpicture → steam -tenfoot (default)
-#   gamepadui  → steam -gamepadui
+Example ~/.gaming-mode.conf
+
+# Launch mode for Steam:
+#   bigpicture (default) → Steam -tenfoot
+#   gamepadui            → Steam -gamepadui
 	STEAM_LAUNCH_MODE=bigpicture
 
-# Performance tweaks:
-#   enabled  → enable gamescope low-latency flags and perf tweaks
-#   disabled → run in a more conservative mode
+# Performance mode:
+#   enabled  → adjust CPU governor + GPU performance settings while gaming
+#   disabled → leave CPU/GPU settings alone
 	PERFORMANCE_MODE=enabled
 
-You can create the file manually or copy from an example:
-
-sudo cp docs/gaming-mode.conf.example /etc/gaming-mode.conf
-sudo $EDITOR /etc/gaming-mode.conf
-
-(User-specific overrides should go in ~/.gaming-mode.conf.)
+You can safely create or edit this file at any time; changes will apply the next time you start Gaming Mode.

Contributing

@@ -0,0 +1,37 @@
+Contributing
+
+Thanks for your interest in contributing to W.O.P.R. 👋
+This repository uses a strict protected-branch workflow to ensure that code cannot change without explicit review and approval.
+
+Contribution Rules
+	•	All changes must be submitted via a pull request (PR).
+	•	The main branch is protected — no one can push to it directly.
+	•	All PRs require approval from the project maintainer before they can be merged.
+	•	At this time, the only maintainer with merge permissions is Gavin Nugent.
+	•	Contributors should fork the repository before making any changes.
+
+This ensures the project remains stable and all modifications are reviewed before entering the codebase.
+
+Ways to Help
+	•	Report bugs (screenshots or logs preferred)
+	•	Improve documentation or spelling/grammar
+	•	Suggest support for additional hardware or compositors
+	•	Propose code cleanups or refactors
+
+How to Submit a Pull Request
+	1.	Fork the repository to your own GitHub account.
+	2.	Create a feature branch in your fork.
+	3.	Make your changes in small, focused commits.
+	4.	If your change affects behaviour, update README.md or relevant docs.
+	5.	Open a pull request against the main branch of this repository.
+	6.	Wait for review. Only approved PRs will be merged.
+
+Style Guidelines
+	•	Target: POSIX-ish bash, using set -Euo pipefail
+	•	Code should be readable and defensive
+	•	Prefer explicit error messages over hidden magic
+	•	Use UK English in user-facing text
+
+Code of Conduct
+
+Be kind, respectful, and constructive. Remember there’s a human on the other side of every issue or pull request.

Known limitations

@@ -0,0 +1,4 @@
+	•	Arch-only: the installer assumes pacman and Arch-style packaging.
+	•	Hyprland-only: it looks specifically for Hypr configs and uses hyprctl.
+	•	Multimonitor setups: Gamescope is launched against your primary output; complex multi-monitor layouts may need extra work.
+	•	Wayland focus: X11 setups are not directly supported.

TROUBLESHOOTING.md

@@ -0,0 +1,89 @@
+# Troubleshooting
+
+A few common issues and fixes when using W.O.P.R.
+
+---
+
+## Gamescope fails to start
+
+**Symptoms**
+
+- You see “ERROR: Gamescope failed to start!”
+- Gaming Mode exits immediately after the spinner
+
+**Things to check**
+
+1. Run `gamescope --help` from a terminal to confirm it is installed.
+2. Make sure your GPU has working Vulkan support:
+   - `vulkaninfo | less` (from `vulkan-tools`)
+3. Confirm you’re on a supported GPU driver:
+   - NVIDIA: `nvidia`, `nvidia-dkms`, or `nvidia-open-dkms`
+   - AMD: `amdgpu` with `vulkan-radeon`
+   - Intel / Arc: recent Mesa recommended
+
+Re-run `./WOPR.sh` to let it re-check dependencies if needed.
+
+---
+
+## Keybinds don’t work
+
+**Symptoms**
+
+- `SUPER`+`SHIFT`+`S` does nothing
+
+**Checks**
+
+1. Open your Hypr config (e.g. `~/.config/hypr/bindings.conf`).
+2. Look for the block:
+
+   ```ini
+   # Gaming Mode bindings - added by installation script
+   ...
+   # End Gaming Mode bindings
+
+
+
+
+3.	Restart Hyprland or reload config: hyprctl reload.
+
+If you use a custom binding file layout, make sure the file W.O.P.R. edited is actually included from your main Hypr config.
+
+
+Steam opens but not in Big Picture
+
+Check ~/.gaming-mode.conf:
+
+STEAM_LAUNCH_MODE=bigpicture
+
+Only two modes are currently supported:
+	•	bigpicture (default)
+	•	gamepadui
+
+
+Performance tweaks don’t seem to apply
+
+Ensure you allowed W.O.P.R. to create the performance udev rules:
+	•	Check for /etc/udev/rules.d/99-gaming-performance.rules.
+
+If you skipped this during installation:
+	1.	Re-run ./WOPR.sh.
+	2.	When prompted about passwordless performance controls, answer Y.
+	3.	Reboot or log out/in to let udev rules take effect.
+
+
+   Intel Arc GTK apps look broken
+
+If you skipped the Intel Arc workaround during install you can run ./WOPR.sh again and accept the Intel Arc GTK4 rendering fix prompt, or manually set:
+
+GSK_RENDERER=gl
+
+in an environment file under /etc/environment.d/ or ~/.config/environment.d/.
+
+
+If you hit something else, please open an issue with:
+	•	Distro + kernel
+	•	GPU model
+	•	Output of ./WOPR.sh (or at least the last 30–40 lines)
+	•	Any relevant Hypr config fragments
+
+

Uninstall

@@ -0,0 +1,29 @@
+
+There isn’t a one-command uninstaller yet, but you can remove everything manually:
+
+1.	Delete launcher scripts
+
+rm -f ~/.local/share/steam-launcher/enter-gamesmode
+rm -f ~/.local/share/steam-launcher/leave-gamesmode
+rmdir ~/.local/share/steam-launcher 2>/dev/null || true
+
+	2.	Remove Hyprland bindings
+
+Edit your bindings config (~/.config/hypr/bindings.conf or similar) and delete the block between:
+
+# Gaming Mode bindings - added by installation script
+...
+# End Gaming Mode bindings
+
+3.    Remove config and state (optional)
+
+rm -f ~/.gaming-mode.conf
+rm -rf ~/.cache/gaming-session
+
+4.	Remove udev rules (optional)
+
+sudo rm -f /etc/udev/rules.d/99-gaming-performance.rules
+sudo udevadm control --reload
+
+	5.	Remove Intel Arc GTK fix (if you enabled it)
+  Delete the created environment file under /etc/environment.d/ or ~/.config/environment.d/ and log out/in.

files and Paths

@@ -0,0 +1,28 @@
+Files and Paths
+	•	Installer script
+  
+		WOPR.sh (this repo)
+    
+	•	Generated launchers
+  
+		~/.local/share/steam-launcher/enter-gamesmode
+		~/.local/share/steam-launcher/leave-gamesmode
+    
+	•	Session state
+  
+		~/.cache/gaming-session/session.pid
+		~/.cache/gaming-session/settings.conf
+    
+	•	Config
+  
+	•	~/.gaming-mode.conf (user)
+	•	/etc/gaming-mode.conf (system)
+  
+		Performance udev rules
+    
+	•	/etc/udev/rules.d/99-gaming-performance.rules
+  
+		Optional Intel Arc GTK4 fix
+    
+	•	e.g. /etc/environment.d/99-intel-arc-gtk4.conf
+or ~/.config/environment.d/99-intel-arc-gtk4.conf