gamectl 1.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,431 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: gamectl
|
|
3
|
+
Version: 1.2.0
|
|
4
|
+
Summary: Sovereign TUI Game Manager & Launcher for Linux & Steam Deck Power Users
|
|
5
|
+
Author-email: zyekhabdul <zyekhabdulqadirjailani@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/zyekhabdul/gamectl
|
|
8
|
+
Project-URL: Repository, https://github.com/zyekhabdul/gamectl.git
|
|
9
|
+
Project-URL: Issues, https://github.com/zyekhabdul/gamectl/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/zyekhabdul/gamectl/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: gamectl,gaming,linux-gaming,steam,proton,steam-deck,wine,tui,cli,launcher,gamescope,mangohud
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
17
|
+
Classifier: Programming Language :: Unix Shell
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
26
|
+
Classifier: Topic :: Games/Entertainment
|
|
27
|
+
Classifier: Topic :: Utilities
|
|
28
|
+
Requires-Python: >=3.8
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
License-File: LICENSE
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
<div align="center">
|
|
34
|
+
|
|
35
|
+
# gamectl
|
|
36
|
+
|
|
37
|
+
### Sovereign TUI Game Manager & Launcher for Linux Purists
|
|
38
|
+
|
|
39
|
+
*Zero Electron. Zero Chromium. Zero Bloat. Sub-80ms Startup.*
|
|
40
|
+
|
|
41
|
+
[](https://github.com/zyekhabdul/gamectl)
|
|
42
|
+
[](https://github.com/zyekhabdul/gamectl)
|
|
43
|
+
[](https://github.com/zyekhabdul/gamectl)
|
|
44
|
+
[](https://github.com/zyekhabdul/gamectl)
|
|
45
|
+
[](https://github.com/zyekhabdul/gamectl)
|
|
46
|
+
[](https://pypi.org/project/gamectl/)
|
|
47
|
+
[](LICENSE)
|
|
48
|
+
[](https://github.com/zyekhabdul/gamectl)
|
|
49
|
+
[](packaging/arch/PKGBUILD)
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# Turnkey Instant Installation
|
|
53
|
+
curl -fsSL https://raw.githubusercontent.com/zyekhabdul/gamectl/main/install.sh | bash
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
[Quickstart](#quick-installation) • [Benchmark](#benchmark-matrix-headless-sovereign-vs-gui-launchers) • [Core Capabilities](#core-capabilities) • [Keyboard Shortcuts](#keyboard-shortcuts-reference) • [CLI Reference](#cli-command-reference) • [Ecosystems](#supported-ecosystems--handhelds) • [Architecture](docs/ARCHITECTURE.md)
|
|
57
|
+
|
|
58
|
+
</div>
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
```text
|
|
63
|
+
╭─ GAMECTL SOVEREIGN COCKPIT ──────────────────┬─ RUNTIME INSPECTION ──────────────────────────────╮
|
|
64
|
+
│ [GBE_FORK] Hades II │ AppID : 1145360 (Hades II) │
|
|
65
|
+
│ [VALVE_DLL] Balatro │ Arch : Windows PE32+ (x86_64) │
|
|
66
|
+
│ [STANDALONE] Dead Cells │ Runner : GE-Proton9-25 (~/.local/share/Steam/) │
|
|
67
|
+
│ [GBE_FORK] Factorio │ Prefix : Isolated ($GAME_DIR/pfx) │
|
|
68
|
+
│ [STANDALONE] Slay the Spire │ Wrappers : GameMode: ON │ MangoHud: ON │ FSR: OFF│
|
|
69
|
+
│ [VALVE_SO] Celeste │ Audio : PipeWire 256/48000 (Low Latency) │
|
|
70
|
+
│ [GBE_FORK] Hollow Knight: Silksong │ Saves : 3-Slot Disaster Guard (slot1/slot2) │
|
|
71
|
+
│ [STANDALONE] Terraria │ Sandbox : Bubblewrap (bwrap: ~/.ssh shielded) │
|
|
72
|
+
│ [VALVE_DLL] Elden Ring │ Isolation : cgroups v2 (systemd-run scope) │
|
|
73
|
+
╰──────────────────────────────────────────────┴───────────────────────────────────────────────────╯
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
**gamectl** is an ultra-lightweight (< 15 MB RAM RSS), high-performance Terminal User Interface (TUI) game manager and launcher designed for Linux workstations and handhelds. It manages, launches, and synchronizes standalone portable games with zero dependency on heavyweight graphical client runtimes (such as Electron, Chromium, or CEF).
|
|
77
|
+
|
|
78
|
+
Engineered for Linux purists and minimalist desktop environments (Wayland / Niri / Sway / Hyprland / X11), `gamectl` delivers instant sub-80ms startup, isolated runtime prefixes, decentralized LAN multiplayer, and disaster-proof savegame snapshotting.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Benchmark Matrix: Headless Sovereign vs GUI Launchers
|
|
83
|
+
|
|
84
|
+
Empirical comparisons measured on Arch Linux x86_64 (Linux kernel 6.x, AMD Ryzen / Intel Core, NVMe storage):
|
|
85
|
+
|
|
86
|
+
| Metric / Dimension | `gamectl` (TUI) | Heroic Games Launcher | Lutris | Bottles |
|
|
87
|
+
| :--- | :--- | :--- | :--- | :--- |
|
|
88
|
+
| **Startup Latency** | **< 80 ms** | ~1,200 - 2,500 ms | ~2,200 - 3,500 ms | ~3,100 - 4,800 ms |
|
|
89
|
+
| **Idle Memory (RSS)** | **< 15 MB** | ~180 - 380 MB | ~120 - 240 MB | ~200 - 420 MB |
|
|
90
|
+
| **Runtime Stack** | **POSIX Bash + fzf + jq** | Electron + Chromium + Node | Python 3 + GTK 3/4 | Python 3 + GTK 4 + libadwaita |
|
|
91
|
+
| **Prefix Architecture** | **Per-game isolated (`./pfx`)** | Global / Managed per game | Shared / Centralized | Flatpak / Centralized bottles |
|
|
92
|
+
| **Savegame Disaster Guard** | **Automated 3-slot rotation** | Manual / Cloud-dependent | None (Manual sync) | Centralized snapshots |
|
|
93
|
+
| **Audio Latency Tuning** | **Automated PipeWire/Pulse** | Manual environment variables | Manual environment variables | Manual environment variables |
|
|
94
|
+
| **Wineserver Teardown** | **Deterministic sync & kill** | Prone to orphan daemons | Prone to lingering processes | Handled via Flatpak sandbox |
|
|
95
|
+
| **Headless / Remote Ops** | **100% Native CLI & TUI** | No (GUI required) | Partial CLI | No (GUI required) |
|
|
96
|
+
| **Asset Overhead** | **Zero bundled web assets** | ~150 - 300 MB disk space | ~80 - 150 MB disk space | ~200 - 400 MB disk space |
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Supported Ecosystems & Handhelds
|
|
101
|
+
|
|
102
|
+
| Ecosystem / Platform | Target Architecture | Support Level | Integration Details |
|
|
103
|
+
| :--- | :--- | :--- | :--- |
|
|
104
|
+
| **Arch Linux / EndeavourOS** | x86_64 | **Native Tier 1** | Standalone binary & `packaging/arch/PKGBUILD` AUR recipe |
|
|
105
|
+
| **Steam Deck (SteamOS)** | AMD Van Gogh (x86_64) | **Native Tier 1** | Desktop Mode TUI + Steam Deck Game Mode (`shortcuts.vdf` + artwork) |
|
|
106
|
+
| **Bazzite / ChimeraOS** | Immutable Linux | **Native Tier 1** | Rootless turnkey installation to `~/.local/bin/` |
|
|
107
|
+
| **Debian / Ubuntu / Linux Mint** | x86_64 | **Verified** | Standard package dependencies via APT |
|
|
108
|
+
| **Fedora / Nobara** | x86_64 | **Verified** | Standard package dependencies via DNF |
|
|
109
|
+
| **Wayland (Niri / Sway / Hyprland)** | Wayland socket pass-through | **Verified** | Full Gamescope FSR & dynamic `$WAYLAND_DISPLAY` binding |
|
|
110
|
+
| **X11 (i3 / bspwm / XFCE)** | Native X11 | **Verified** | Automatic `$XAUTHORITY` and DISPLAY detection |
|
|
111
|
+
| **Handheld PCs (ROG Ally, Legion Go)** | AMD Phoenix / Z1 Extreme | **Verified** | Low-overhead execution freeing maximum VRAM for 3D shaders |
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## Core Capabilities
|
|
116
|
+
|
|
117
|
+
- **Zero-Bloat & Instant Startup**: Written in pure POSIX Bash, `fzf`, and `jq`. Cuts 95%+ memory overhead compared to conventional graphical game launchers.
|
|
118
|
+
- **Dynamic Multi-Library Autodetection**: Automatically scans and aggregates games across all Steam library partitions (`libraryfolders.vdf` + ACF manifests), portable directories (`~/Games/`), Lutris paths, and custom locations via `~/.config/gamectl/libraries` or `GAMECTL_LIBRARY_DIRS`.
|
|
119
|
+
- **Split-Pane Live Inspection Cockpit**: Left pane lists your library with ANSI status badges; right pane streams real-time binary architectures (ELF 32/64-bit, PE32/PE32+), runner paths, wrapper profiles, LAN multiplayer personas, and savegame sizes.
|
|
120
|
+
- **cgroups v2 Process Tree Isolation (`gamectl launch --scope`)**: Encapsulates game execution in a dedicated systemd user scope (`gamectl-<title>-<pid>`), terminating all background helpers (`winedevice.exe`, `explorer.exe`, crash reporters) atomically on exit with zero zombie processes.
|
|
121
|
+
- **Automated PRIME Hybrid dGPU Offload (`gamectl launch --prime`)**: Auto-probes `/sys/bus/pci/devices/` and routes rendering to secondary discrete NVIDIA (`__NV_PRIME_RENDER_OFFLOAD=1`), AMD, or Intel Arc (`DRI_PRIME=1`) controllers without manual environment variable hacking.
|
|
122
|
+
- **Rootless Bubblewrap Security Sandbox (`gamectl launch --sandbox`)**: Mounts host root as read-only and shields private directories (`~/.ssh`, `~/.gnupg`, browser cookies, and `.env` credentials) inside a hardened tmpfs namespace while transparently passing Wayland/X11 and PipeWire audio sockets.
|
|
123
|
+
- **Disaster-Proof Savegame Snapshots**: Automatically creates a 3-slot rotating backup (`slot1`, `slot2`, `slot3`) before each game launch, safeguarding your save states against crashes and dirty shutdowns.
|
|
124
|
+
- **Decentralized LAN Steam Emulator (`gamectl inject`)**: Converts Valve binaries (Linux native `.so` and Windows `.dll` x86/x64) into portable standalone runtimes featuring local `./saves` redirection and automated `steam_settings/DLC.txt` generation.
|
|
125
|
+
- **Isolated Windows Runner & Prefix Engine**: Discovers installed Windows compatibility runners (`umu-run` -> `GE-Proton` / Steam `Proton` -> `wine`) and maintains strictly isolated prefixes in `$GAME_DIR/pfx`, keeping host `~/.wine` pristine.
|
|
126
|
+
- **Modular Performance Wrappers**: On-the-fly toggle for `gamemoderun`, `mangohud`, `gamescope` dynamic FSR upscaling, and Mesa multithreaded GL via interactive dialogs (`<Ctrl-O>`) or CLI flags.
|
|
127
|
+
- **LAN Multi-Identity & SteamID Manager (`gamectl set-id`)**: Generates deterministic 17-digit SteamID64 tokens and distinct LAN gamer tags to prevent co-op network collisions, with custom peer discovery (`custom_broadcasts.txt`).
|
|
128
|
+
- **Headless Asset Downloader Engine (`gamectl download`)**: Downloads game files directly from content servers via DepotDownloader CLI in foreground or detached background modes without requiring a GUI client.
|
|
129
|
+
- **Steam Entitlement & ACF Adoption Engine (`gamectl entitle`, `gamectl adopt-steam`)**: Adopts local/offline files into the official Steam client, unlocking community Steam Input mappings (gyro/touchpad), Valve CDN Vulkan shader pre-caching, and base-game DLC activation via `~/.config/SLSsteam/config.yaml` and native `appmanifest_<appid>.acf`. (Backward-compatible alias: `gamectl unlock`).
|
|
130
|
+
- **Universal Mod DLL Overrides & P2P Hook Engine (`gamectl mod-overrides`)**: Detects mod loaders and P2P compatibility layers (BepInEx, UE4SS, REFramework, ReShade, OnlineFix), injects deduplicated `WINEDLLOVERRIDES`, and registers Spacewar AppID 480.
|
|
131
|
+
- **Headless GE-Proton Release Manager (`gamectl proton-*`)**: Fetches upstream GitHub releases, streams tarball installation directly into `~/.local/share/Steam/compatibilitytools.d/`, and prunes older versions safely.
|
|
132
|
+
- **Wine Prefix Swiss Army Knife (`gamectl pfx`) & Wineserver Guard**: Dedicated maintenance toolkit (`winecfg`, `regedit`, `cmd`, `shell`, `winetricks`, `kill`, `clean`) with deterministic wineserver teardown (`wineserver -w` / `-k`) to eliminate registry lock contention.
|
|
133
|
+
- **Real-Time PipeWire Audio Scheduling**: Exports optimal quantum buffer configurations (`PIPEWIRE_LATENCY="256/48000"`, `PULSE_LATENCY_MSEC=60`) to prevent audio crackling and buffer starvation during high CPU spikes.
|
|
134
|
+
- **One-Key Multi-Node Sync (`<Ctrl-S>`)**: Synchronizes portable save states to secondary handhelds or remote servers over SSH/Rsync with pre-flight network checks.
|
|
135
|
+
- **Steam Store Catalog & ProtonDB Compatibility Audit**: Fast online search integrating public Steam Store metadata with live ProtonDB Linux compatibility tier ratings (Native, Platinum, Gold, Silver, Bronze, Borked).
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Keyboard Shortcuts Reference
|
|
140
|
+
|
|
141
|
+
The interactive TUI library navigation provides instantaneous single-keystroke operations:
|
|
142
|
+
|
|
143
|
+
| Shortcut | Action Description |
|
|
144
|
+
| :--- | :--- |
|
|
145
|
+
| `<ENTER>` | Launch Game (Automatic save snapshot + runner resolution + wrappers) |
|
|
146
|
+
| `<Ctrl-O>` | Configure Runtime Wrappers (GameMode / MangoHud / Gamescope FSR / Mesa GL) |
|
|
147
|
+
| `<Ctrl-P>` | Configure LAN Multiplayer Gamer Tag & SteamID64 Persona |
|
|
148
|
+
| `<Ctrl-I>` | Inject Decentralized LAN Runtime & Entitlement Sync |
|
|
149
|
+
| `<Ctrl-S>` | Sync Portable Savegame to Remote Companion Host via SSH |
|
|
150
|
+
| `<Ctrl-B>` | Create Manual Savegame Snapshot Slot |
|
|
151
|
+
| `<Ctrl-F>` | Search Steam Store Catalog & Audit ProtonDB Rating |
|
|
152
|
+
| `<Ctrl-D>` | Open Background Download Monitor |
|
|
153
|
+
| `<ESC>` / `<Ctrl-C>` | Return to Master Dashboard Hub / Exit |
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Multi-Platform Installation
|
|
158
|
+
|
|
159
|
+
### Option 1: Turnkey One-Liner (Universal Linux & Steam Deck)
|
|
160
|
+
```bash
|
|
161
|
+
curl -fsSL https://raw.githubusercontent.com/zyekhabdul/gamectl/main/install.sh | bash
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Option 2: Arch Linux (AUR & AUR-Git)
|
|
165
|
+
```bash
|
|
166
|
+
# Release package:
|
|
167
|
+
yay -S gamectl
|
|
168
|
+
# or development branch (VCS):
|
|
169
|
+
paru -S gamectl-git
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### Option 3: Debian / Ubuntu (.deb Package)
|
|
173
|
+
```bash
|
|
174
|
+
# Build and install Debian package:
|
|
175
|
+
make pkg-deb
|
|
176
|
+
sudo dpkg -i packaging/debian/gamectl_1.2.0_all.deb
|
|
177
|
+
sudo apt install -f
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Option 4: Homebrew Tap (Linux & macOS)
|
|
181
|
+
```bash
|
|
182
|
+
brew tap zyekhabdul/tap
|
|
183
|
+
brew install gamectl
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Option 5: Nix Flake (NixOS / Declarative)
|
|
187
|
+
```bash
|
|
188
|
+
# Run directly without installation:
|
|
189
|
+
nix run github:zyekhabdul/gamectl
|
|
190
|
+
|
|
191
|
+
# Or add to your NixOS flake inputs:
|
|
192
|
+
# inputs.gamectl.url = "github:zyekhabdul/gamectl";
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### Option 6: Python Package (pipx & pip)
|
|
196
|
+
```bash
|
|
197
|
+
# Recommended for modern Linux (PEP 668):
|
|
198
|
+
pipx install gamectl
|
|
199
|
+
|
|
200
|
+
# Or inside standard virtualenv:
|
|
201
|
+
pip install gamectl
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
### Option 7: Manual Source Clone & Turnkey Installer
|
|
205
|
+
```bash
|
|
206
|
+
git clone git@github.com:zyekhabdul/gamectl.git
|
|
207
|
+
cd gamectl
|
|
208
|
+
./install.sh
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
The turnkey installer automatically executes:
|
|
212
|
+
1. Compiles or symlinks standalone binary `gamectl` and shorthand alias `game` to `~/.local/bin/`.
|
|
213
|
+
2. Scaffolds configuration directory and templates in `~/.config/gamectl/`.
|
|
214
|
+
3. Installs shell completion script to `~/.local/share/bash-completion/completions/gamectl`.
|
|
215
|
+
4. Registers FreeDesktop entry `gamectl.desktop` for Wayland/X11 application launchers (rofi, fuzzel, wofi, dmenu).
|
|
216
|
+
5. Verifies runtime availability of headless tools (DepotDownloader, compatibility templates).
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## CLI Command Reference
|
|
221
|
+
|
|
222
|
+
`gamectl` is fully operational as both an interactive TUI and a scriptable CLI tool:
|
|
223
|
+
|
|
224
|
+
### 1. Interactive TUI Navigation
|
|
225
|
+
```bash
|
|
226
|
+
gamectl # Launch Master Dashboard Hub TUI
|
|
227
|
+
gamectl library # Open Game Library TUI directly (alias: list-ui)
|
|
228
|
+
gamectl config # Open global configuration editor (alias: configure)
|
|
229
|
+
gamectl doctor # Run 7-layer system & GPU health diagnostics (alias: audit)
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
### 2. Launching Games
|
|
233
|
+
```bash
|
|
234
|
+
# Launch with MangoHud and GameMode enabled:
|
|
235
|
+
gamectl launch "$HOME/Games/DeadCells" --hud --gamemode
|
|
236
|
+
|
|
237
|
+
# Launch Windows executable with Gamescope FSR upscaling:
|
|
238
|
+
gamectl launch "$HOME/Games/WindowsGame" game.exe --gamescope --fsr
|
|
239
|
+
|
|
240
|
+
# Launch with cgroups v2 process tree isolation (systemd-run scope):
|
|
241
|
+
gamectl launch "$HOME/Games/HeavyGame" --scope
|
|
242
|
+
|
|
243
|
+
# Launch with automated PRIME hybrid discrete GPU offloading (NVIDIA / AMD / Intel Arc):
|
|
244
|
+
gamectl launch "$HOME/Games/3DGame" --prime
|
|
245
|
+
|
|
246
|
+
# Launch inside rootless Bubblewrap (bwrap) security sandbox (shielding ~/.ssh, ~/.gnupg, cookies):
|
|
247
|
+
gamectl launch "$HOME/Games/UntrustedGame" --sandbox
|
|
248
|
+
|
|
249
|
+
# Configure per-game wrapper persistence:
|
|
250
|
+
gamectl configure-wrappers "$HOME/Games/DeadCells"
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
### 3. Linux Kernel Isolation & Hardware Diagnostics
|
|
254
|
+
```bash
|
|
255
|
+
# Detect discrete secondary GPU vendor on hybrid laptop/desktop systems:
|
|
256
|
+
gamectl detect-gpu
|
|
257
|
+
|
|
258
|
+
# Check if systemd-run user scope cgroups v2 isolation is supported:
|
|
259
|
+
gamectl check-scope
|
|
260
|
+
|
|
261
|
+
# Check if Bubblewrap rootless sandbox profile is available:
|
|
262
|
+
gamectl check-sandbox
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### 4. P2P Multiplayer Compatibility & Mod DLL Overrides
|
|
266
|
+
```bash
|
|
267
|
+
# Setup P2P compatibility layer, DLL overrides, and Spacewar AppID 480:
|
|
268
|
+
gamectl mod-overrides "$HOME/Games/CoopGame"
|
|
269
|
+
|
|
270
|
+
# Backward-compatible command alias:
|
|
271
|
+
gamectl onlinefix "$HOME/Games/CoopGame"
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
### 5. GE-Proton Release Manager
|
|
275
|
+
```bash
|
|
276
|
+
# Query installed local releases vs latest upstream releases on GitHub:
|
|
277
|
+
gamectl proton-list
|
|
278
|
+
|
|
279
|
+
# Install latest GE-Proton release (or specify version tag):
|
|
280
|
+
gamectl proton-install latest
|
|
281
|
+
gamectl proton-install GE-Proton9-25
|
|
282
|
+
|
|
283
|
+
# Safely remove an obsolete GE-Proton version:
|
|
284
|
+
gamectl proton-remove GE-Proton8-26
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
### 6. Wine Prefix Swiss Army Knife (`pfx`)
|
|
288
|
+
```bash
|
|
289
|
+
# Open interactive prefix management menu:
|
|
290
|
+
gamectl pfx "$HOME/Games/MyGame"
|
|
291
|
+
|
|
292
|
+
# Execute Windows utilities inside the isolated prefix:
|
|
293
|
+
gamectl pfx "$HOME/Games/MyGame" winecfg
|
|
294
|
+
gamectl pfx "$HOME/Games/MyGame" regedit
|
|
295
|
+
gamectl pfx "$HOME/Games/MyGame" cmd
|
|
296
|
+
gamectl pfx "$HOME/Games/MyGame" shell
|
|
297
|
+
gamectl pfx "$HOME/Games/MyGame" winetricks d3dx9 vcrun2022
|
|
298
|
+
|
|
299
|
+
# Teardown stuck wineserver processes gracefully (DEFECT-02):
|
|
300
|
+
gamectl pfx "$HOME/Games/MyGame" kill
|
|
301
|
+
|
|
302
|
+
# Reset prefix with automatic savegame backup:
|
|
303
|
+
gamectl pfx "$HOME/Games/MyGame" clean -y
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
### 7. Decentralized LAN Steam Runtime & Portable Saves
|
|
307
|
+
```bash
|
|
308
|
+
# Inject standalone LAN runtime and sync offline entitlement (All-in-One):
|
|
309
|
+
gamectl inject "$HOME/Games/Limbo" 48000
|
|
310
|
+
|
|
311
|
+
# Inject standalone LAN runtime only (zero Steam client sync):
|
|
312
|
+
gamectl inject "$HOME/Games/Limbo" 48000 --no-sync
|
|
313
|
+
|
|
314
|
+
# Configure LAN player persona and SteamID64:
|
|
315
|
+
gamectl set-id "PlayerTwo" auto "$HOME/Games/Valheim"
|
|
316
|
+
gamectl set-id "Alice" 76561198123456789 "$HOME/Games/Valheim" --broadcast "192.168.1.50"
|
|
317
|
+
gamectl set-id "MyGamerTag" auto --global
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
### 8. Headless Asset Downloader Engine
|
|
321
|
+
```bash
|
|
322
|
+
# Download game files, inject decentralized runtime, and sync entitlement:
|
|
323
|
+
gamectl download 48000 "$HOME/Games/Limbo" "LIMBO"
|
|
324
|
+
|
|
325
|
+
# Download game assets only without injection:
|
|
326
|
+
gamectl download 48000 "$HOME/Games/Limbo" "LIMBO" --raw
|
|
327
|
+
|
|
328
|
+
# Run download in foreground (live stream logs):
|
|
329
|
+
gamectl download 48000 "$HOME/Games/Limbo" "LIMBO" -f
|
|
330
|
+
|
|
331
|
+
# Monitor active and completed download tasks:
|
|
332
|
+
gamectl downloads
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
### 9. Steam Entitlement & ACF Adoption Engine (Zero-Download Full DLC)
|
|
336
|
+
Adopts offline or standalone game files into the official Steam client, enabling community Steam Input (gyro/trackpad profiles), Valve CDN Vulkan shader pre-caching, and full DLC entitlement without re-downloading:
|
|
337
|
+
|
|
338
|
+
```bash
|
|
339
|
+
# Entitle AppID, adopt local assets, and register full DLC into Steam:
|
|
340
|
+
gamectl entitle 1145360 "Hades II" # Aliases: unlock, adopt-steam
|
|
341
|
+
|
|
342
|
+
# Synchronize installed standalone game files with Steam client:
|
|
343
|
+
gamectl sync-steam 427520 "Factorio" "$HOME/Games/Factorio"
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
### 10. ProtonDB Compatibility Audit & Shortcuts
|
|
347
|
+
```bash
|
|
348
|
+
# Query ProtonDB rating by AppID:
|
|
349
|
+
gamectl protondb 105600
|
|
350
|
+
|
|
351
|
+
# Query ProtonDB rating by game directory:
|
|
352
|
+
gamectl protondb "$HOME/Games/Terraria"
|
|
353
|
+
|
|
354
|
+
# Generate FreeDesktop .desktop application launcher:
|
|
355
|
+
gamectl make-desktop "$HOME/Games/Terraria" "Terraria"
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
### 11. Multi-Node Savegame Synchronization
|
|
359
|
+
```bash
|
|
360
|
+
# Synchronize local savegame snapshots to configured remote companion host:
|
|
361
|
+
gamectl --sync "$HOME/Games/Terraria" "Terraria"
|
|
362
|
+
|
|
363
|
+
# Create immediate manual save snapshot:
|
|
364
|
+
gamectl --backup "$HOME/Games/Terraria"
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
---
|
|
368
|
+
|
|
369
|
+
## Configuration & Environment Variables
|
|
370
|
+
|
|
371
|
+
`gamectl` respects XDG Base Directory standards and standard Linux configuration paths:
|
|
372
|
+
|
|
373
|
+
| File / Variable | Description |
|
|
374
|
+
| :--- | :--- |
|
|
375
|
+
| `~/.config/gamectl/libraries` | Plaintext list of custom game library search paths (one per line). |
|
|
376
|
+
| `~/.config/gamectl/wrappers` | Global default wrapper preferences (`gamemode=1`, `hud=1`, `gamescope=0`). |
|
|
377
|
+
| `~/.config/gamectl/remote_host` | Hostname or IP of companion remote sync node (`user@hostname`). |
|
|
378
|
+
| `~/.config/gamectl/persona` | Global default player gamer tag and SteamID64. |
|
|
379
|
+
| `GAMECTL_LIBRARY_DIRS` | Environment variable to inject extra library search paths dynamically. |
|
|
380
|
+
| `XDG_RUNTIME_DIR/gamectl-$UID/` | Ephemeral runtime directory for active game tracking and locks. |
|
|
381
|
+
|
|
382
|
+
---
|
|
383
|
+
|
|
384
|
+
## Project Structure
|
|
385
|
+
|
|
386
|
+
```text
|
|
387
|
+
gamectl/
|
|
388
|
+
├── bin/
|
|
389
|
+
│ └── gamectl # Monolithic standalone compiled executable (source-to-bundle)
|
|
390
|
+
├── completions/
|
|
391
|
+
│ └── gamectl.bash # Shell autocompletion script (Bash / Zsh)
|
|
392
|
+
├── docs/
|
|
393
|
+
│ ├── ARCHITECTURE.md # Deep dive into headless Linux game management architecture
|
|
394
|
+
│ └── GUIDE.md # Operational handbook, prefix isolation, and disaster recovery
|
|
395
|
+
├── packaging/
|
|
396
|
+
│ └── arch/ # Arch Linux PKGBUILD packaging recipes
|
|
397
|
+
├── scripts/
|
|
398
|
+
│ ├── build.sh # Source-to-bundle deterministic compilation script
|
|
399
|
+
│ └── format.sh # Shell formatting and lint harness
|
|
400
|
+
├── src/
|
|
401
|
+
│ ├── core/ # Header constants, ANSI palette, snapshot engine, utils
|
|
402
|
+
│ ├── diagnostics/ # 7-layer system health audit and ProtonDB client
|
|
403
|
+
│ ├── runners/ # Windows runners, prefix manager, DLL overrides, launcher HUD
|
|
404
|
+
│ ├── steam/ # Multi-path discovery, identity, and headless downloader
|
|
405
|
+
│ ├── tui/ # Master dashboard hub, preview cards, interactive search
|
|
406
|
+
│ └── main.sh # Subshell exports and CLI command dispatcher
|
|
407
|
+
├── tests/
|
|
408
|
+
│ └── test_cli.sh # Comprehensive regression & integrity harness (50+ tests)
|
|
409
|
+
├── gamectl.desktop # FreeDesktop application launcher entry
|
|
410
|
+
├── install.sh # Turnkey installation script
|
|
411
|
+
└── README.md # Project manifesto, benchmarks, and command dictionary
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
---
|
|
415
|
+
|
|
416
|
+
## Community & Stargazers
|
|
417
|
+
|
|
418
|
+
If `gamectl` freed your RAM, eliminated background browser bloat, or improved your Linux gaming workflow, consider starring the repository on GitHub!
|
|
419
|
+
|
|
420
|
+
[](https://star-history.com/#zyekhabdul/gamectl&Date)
|
|
421
|
+
|
|
422
|
+
- **Issues & Discussions**: Found an edge-case or want to propose an optimization? Open an issue on GitHub.
|
|
423
|
+
- **Contributions**: Packaging recipes (Nix, Flatpak, Void, Alpine) and hardware profiles are welcome via Pull Requests.
|
|
424
|
+
|
|
425
|
+
---
|
|
426
|
+
|
|
427
|
+
## License & Legal Notice
|
|
428
|
+
|
|
429
|
+
Distributed under the MIT License. See `LICENSE` for details.
|
|
430
|
+
|
|
431
|
+
`gamectl` is an independent open-source utility designed for managing standalone local game files and compatibility runners on Linux. It does not distribute, host, or bypass proprietary encryption on copyrighted game software. All trademarks and brand names belong to their respective owners.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
gamectl-1.2.0.dist-info/licenses/LICENSE,sha256=cImlkVJ2ze_Gc1TMhqQ_puPOmdFRsmC9CQNigsdiZbc,1068
|
|
2
|
+
gamectl_runner/__init__.py,sha256=xF0OBaWHAPflbRr4F4cwLLFCE3SEtMFofBr4cd-cXCY,1557
|
|
3
|
+
gamectl-1.2.0.dist-info/METADATA,sha256=b6_Eq8PX7ADR8r5jRy1YAQZFEebQiETHz4aIvq_Vtsk,23558
|
|
4
|
+
gamectl-1.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
5
|
+
gamectl-1.2.0.dist-info/entry_points.txt,sha256=NSFwGWZcZRG-FxCfth123ZDkVvfUqTo4irAck_Raq24,75
|
|
6
|
+
gamectl-1.2.0.dist-info/top_level.txt,sha256=PwC4AxlE3Y7BVtrmCTHVYWm9V4603dMAR30raLo9Zvg,15
|
|
7
|
+
gamectl-1.2.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Zyekh Abdul
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
gamectl_runner
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
"""gamectl runner - Python shim for sovereign native gamectl CLI."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
import shutil
|
|
7
|
+
import sys
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def get_bundled_bin() -> Path:
|
|
12
|
+
"""Locate bundled gamectl executable."""
|
|
13
|
+
# 1. Check inside package directory (installed wheel)
|
|
14
|
+
pkg_bin = Path(__file__).parent / "bin" / "gamectl"
|
|
15
|
+
if pkg_bin.is_file():
|
|
16
|
+
return pkg_bin
|
|
17
|
+
|
|
18
|
+
# 2. Check repo root if running in editable/dev mode
|
|
19
|
+
repo_bin = Path(__file__).resolve().parent.parent.parent / "bin" / "gamectl"
|
|
20
|
+
if repo_bin.is_file():
|
|
21
|
+
return repo_bin
|
|
22
|
+
|
|
23
|
+
# 3. Check PATH for existing system gamectl
|
|
24
|
+
system_bin = shutil.which("gamectl")
|
|
25
|
+
if system_bin:
|
|
26
|
+
return Path(system_bin)
|
|
27
|
+
|
|
28
|
+
raise FileNotFoundError("gamectl: bundled standalone executable not found")
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def main() -> None:
|
|
32
|
+
"""Entrypoint executing bundled gamectl binary via bash."""
|
|
33
|
+
try:
|
|
34
|
+
bin_path = get_bundled_bin()
|
|
35
|
+
except FileNotFoundError as err:
|
|
36
|
+
sys.stderr.write(f"Error: {err}\n")
|
|
37
|
+
sys.exit(1)
|
|
38
|
+
|
|
39
|
+
# Ensure executable permissions
|
|
40
|
+
if not os.access(bin_path, os.X_OK):
|
|
41
|
+
try:
|
|
42
|
+
bin_path.chmod(bin_path.stat().st_mode | 0o755)
|
|
43
|
+
except OSError:
|
|
44
|
+
pass
|
|
45
|
+
|
|
46
|
+
# Delegate directly to bash, replacing current process
|
|
47
|
+
try:
|
|
48
|
+
os.execvp("bash", ["bash", str(bin_path), *sys.argv[1:]])
|
|
49
|
+
except FileNotFoundError:
|
|
50
|
+
sys.stderr.write("gamectl: 'bash' executable required but not found in PATH\n")
|
|
51
|
+
sys.exit(1)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
if __name__ == "__main__":
|
|
55
|
+
main()
|