How can we help you
with AGONY Hub?

AGONY Hub v1.0.0 is distributed as an official, self-contained Windows 64-bit installer executable (AGONY Hub Setup 1.0.0.exe, exactly 93,818,896 bytes).

System Requirements:

• Operating System: Windows 10 (64-bit, Build 19041+) or Windows 11 (64-bit).
• Hardware: 64-bit multi-core CPU, 4 GB RAM, and at least 500 MB free disk space.
• Privileges: Standard user account. AGONY Hub installs into your Windows user directory without requiring Administrator UAC elevation.

Step-by-Step Installation:

1. Download Installer: Visit the official Download page or click Download Now. Verify the file size is 89.47 MB (93,818,896 bytes).
2. Run Setup: Double-click AGONY Hub Setup 1.0.0.exe.
3. Review License: Read and accept the AGONY Hub End-User Commercial License.
4. Installation Location: Setup installs automatically to:
   %LOCALAPPDATA%\Programs\AGONY Hub
5. Shortcuts & Finish: Choose whether to create Desktop and Start Menu shortcuts, click Install, and finish setup.

AGONY Hub Setup 1.0.0 • NSIS Installation Wizard Windows 64-bit

Figure 1.1: Official AGONY Hub v1.0.0 installation wizard welcome screen.

When AGONY Hub launches for the first time with an unpopulated library, the First-Run Platform Discovery modal (#first-run-modal) automatically appears.

1. First-Run Discovery Setup:

AGONY Hub checks standard system locations for installed platforms on your PC and presents available options:

• Steam Platform: Discovers Steam games through registry detection and manifest scans.
• Epic Games: Reads official Epic manifest items from ProgramData.
• Xbox / Windows Apps: Discovers installed Microsoft Store / UWP gaming packages.

Click Import Selected Platforms (#first-run-import-btn) to scan your libraries automatically, or click Skip (#first-run-skip-btn) to start with an empty library.

2. Topbar Navigation Tabs:

The frameless minimal-luxury titlebar and header contain 5 main navigation views:

• Library (#nav-library): Grid, Compact, or List view of all orchestrated games.
• Favorites (#nav-favorites): Quick-filter showing only games you have starred.
• Dashboard (#nav-dashboard): Visual gaming analytics, total playtime counter, and platform breakdown.
• WAND (#wand-open): Opens the WAND Control Center dialog (revealed when WAND is enabled in Settings).
• Settings (#nav-settings): Preferences, themes, Spotify, updater, and system configuration.

3. Language & RTL Switching:

Click the العربية / English toggle (#topbar-lang-toggle) in the topbar. AGONY Hub instantly toggles between English and Arabic, flipping the entire interface to native Right-to-Left (RTL) mode with localized menus and tooltips.

AGONY Hub v1.0.0 • Main Interface & Library Grid Unified Orchestration

Figure 1.2: AGONY Hub v1.0.0 main interface with topbar navigation, search, and unified library grid.

AGONY Hub uses a cryptographic licensing architecture combining Ed25519 digital signatures, 72-hour offline validity leases, and Windows DPAPI local encryption.

1. Account Registration & Instant Free Tier:

When you create an account on the website or in the desktop Welcome Modal, new accounts receive instant approval (status: 'approved') and are immediately provisioned with a Free tier license.

2. 72-Hour Offline Cryptographic Leases:

During login or license refresh, the Cloudflare Edge server issues an Ed25519 digitally signed lease valid for 72 hours, encrypted via Windows DPAPI to %APPDATA%\AGONY Hub\license.dat. You can launch your games offline for up to 3 days without internet access.

3. Free vs. Premium Feature Comparison:

4. Account Status & Suspension Enforcement:

The topbar badge displays your authoritative account status: FREE, PREMIUM, or OWNER. If an account is suspended:

• Server sessions are revoked and the local offline lease is immediately invalidated.
• Core launcher operations (launch-game, launch-wand) are fail-closed and return ACCOUNT_SUSPENDED.
• The desktop displays the red shield Account Suspended lock screen with a Sign In with Another Account button.
• Data Safety Guarantee: Suspending an account never deletes or alters your installed games in %APPDATA%\AGONY Hub\library.json.

Click Settings (#nav-settings) in the topbar to configure your preferences.

Core Settings Sections:

• Appearance & Animation: Interface language selector (English / العربية), Reduced Motion toggle, Auto Theme Engine indicator, and Open Theme Library.
• Background Effects: Atmosphere Mode selector (Off, Rain, Snow) and Effect Intensity (Low, High).
• Platform & Data: Launch Quietly toggle (avoids foreground platform windows), Product Version indicator (v1.0.0), and Check for Updates.
• Integrations: Enable WAND Integration toggle, availability diagnostics, and WAND Control Center actions.
• Spotify Media Integration: Local SMTC & WASAPI status, Open Spotify, Check Status, and optional Custom Connection… dialog.
• Online Artwork Provider (SteamGridDB): Optional API key configuration for community cover artwork.

AGONY Hub integrates directly with official local launcher manifests, ensuring instant synchronization without downloading duplicate binaries.

1. Importing Steam Games:

Click Import Steam (#import-steam) in the topbar:

1. AGONY Hub resolves the Steam install path from the Windows registry (HKCU\Software\Valve\Steam\SteamPath).
2. Parses steamapps/libraryfolders.vdf to discover secondary library folders across all mounted drives.
3. Scans appmanifest_<id>.acf files to verify installation states, numeric App IDs, and executable paths.
4. Launches via the official Steam URI protocol (steam://rungameid/<AppID>) or Steam client launch with arguments.

2. Importing Epic Games:

Click Import Epic (#import-epic) in the topbar:

1. Scans official manifest records in %PROGRAMDATA%\Epic\EpicGamesLauncher\Data\Manifests\*.item.
2. Extracts canonical AppName, DisplayName, InstallLocation, and LaunchExecutable.
3. Launches using the documented Epic Games Launcher protocol:
   com.epicgames.launcher://apps/<AppName>?action=launch&silent=true

AGONY Hub supports Microsoft Store / Xbox Game Pass titles and DRM-free standalone PC executables.

1. Adding Xbox & Windows Apps:

Click Add Xbox Game (#add-xbox) in the topbar to open the Xbox modal (#xbox-modal):

• Discovered Xbox Games Tab: Scans %LOCALAPPDATA%\Packages for installed UWP applications and resolves Application User Model IDs (AUMIDs). Click Add next to any discovered title to add it to your library. AGONY Hub launches it via shell:AppsFolder\<AUMID>.
• Custom Windows App Tab: For titles installed in custom directories (e.g. C:\XboxGames), enter the Title, Target Folder / EXE, and Launch Type (UWP, Win32, or Gameloop).

AGONY Hub • Discovered Xbox Titles Modal UWP AUMID Execution

Figure 2.1: Xbox & Windows App discovery modal with 1-click addition.

2. Adding Standalone Games Manually:

Click + Add Game (#add) in the topbar:

1. Browse to any Windows game binary (.exe) on your PC and select it.
2. AGONY Hub extracts product information, title metadata, and configures the working directory.

AGONY Hub respects official launcher protocols and supports two primary execution modes:

1. Normal Launch Mode:

The default mode for all games. Starts titles using official platform protocols (steam://, com.epicgames.launcher://, shell:AppsFolder\) or direct Win32 process spawning for standalone binaries, ensuring game updates, cloud saves, and achievements remain synchronized.

2. WAND Launch Mode (Optional):

Available when WAND Integration is enabled. Routes game startup through WAND / WeMod to attach modded trainers and apply customized visual theme profiles.

3. Launch Options & Profiles:

In the Game Details modal (#game-detail-modal), click Options to configure:

• Custom Arguments: Pass command-line parameters (e.g. -novid -dx11) to the executable.
• Administrator Elevation: Automatically triggers RunAsAdmin if a game binary requires elevated system permissions.
• Launch Mode Toggle: Switch between Normal and WAND mode per game.

AGONY Hub gives you fine-grained control over artwork, card density, custom collections, and library health diagnostics.

1. Library Health Telemetry Panel:

Located in the left sidebar, the Library health panel displays real-time counters:

• Missing artwork: Number of titles without portrait covers.
• Missing executable: Number of titles whose executable path is currently inaccessible on disk.
• Unverified installs: Games requiring path or metadata validation.
• Total games: Total orchestrated game count.

2. Artwork Assignment:

In the Game Details modal:

• Click Cover Art (#detail-cover-local) to select a local portrait image (recommended: 600x900).
• Click Background Art (#detail-bg-local) to select a wide 16:9 ambient backdrop image.
• Click Search Online (#detail-artwork) to search Steam Store CDN (zero keys needed) or SteamGridDB (if API key is configured).

AGONY Hub • Online Artwork Search Dialog Steam Store • SteamGridDB

Figure 2.2: Online artwork search dialog with category tabs and 1-click apply.

3. Sorting, Filters & View Modes:

• View Modes: Grid, Compact, and List view (#view-grid, #view-compact, #view-list).
• Card Density / Size: Small, Medium, Large dropdown (#card-size).
• Sorting: A–Z, Z–A, Most played, Recently played, Recently added, and Source platform.
• Collections: Create custom collections (#btn-new-collection) in the sidebar to organize games by genre or series.

AGONY Hub allows you to personalize your workspace using preset luxury color points or any custom hex accent.

1. Preset Accents:

Click the accent color dot (#theme-color-btn) in the topbar to open the Palette Popover. Choose from 7 built-in accents:

• Purple (Default): #8b5cf6 • Classic AGONY Obsidian Violet
• Blue: #3b82f6 • Royal Cobalt
• Teal: #14b8a6 • Nordic Cyan
• Red: #ef4444 • Crimson Eclipse
• Amber: #f59e0b • Champagne Gold
• Emerald: #10b981 • Sovereign Green
• Cyberpunk: #06b6d4 • High-Tech Cyan

2. Custom Accent Color Picker (Premium):

In the popover, click the color swatch next to Custom Accent (#theme-custom-picker) to open the Windows native color picker and select any 24-bit hex value.

When Auto Theme (#theme-auto-toggle) is active, AGONY Hub harmonizes the entire desktop atmosphere with the game currently in focus.

1. Artwork Color Quantization:

When you click a game card in your library, AGONY Hub's color quantization engine analyzes the game's high-resolution cover artwork. It extracts the primary vibrant hue, generates balanced secondary accents, and computes high-contrast surface glows.

2. The Click-to-Commit Invariant:

3. Persisting Selected Game State:

In Settings → Platform & Data, the Selected Game State shows Preserved. When you close AGONY Hub, your active game selection and its extracted palette are stored in %APPDATA%\AGONY Hub\settings.json and restored automatically on next launch.

AGONY Hub features an ambient background particle engine that renders cinematic rain and snow behind library cards.

1. Configuring Atmosphere (Settings → Background Effects):

• Off (#bg-effect-off): Completely disables particle canvas rendering.
• Rain (#bg-effect-rain): Renders angled, translucent streaks falling smoothly across the obsidian backdrop.
• Snow (#bg-effect-snow): Renders floating, drifting snowflakes with subtle horizontal sway.
• Intensity: Toggle between Low (subtle density) and High (cinematic density).

2. Performance Guard & Auto-Pausing:

The Atmosphere engine is capped at 30 FPS (<1% GPU overhead). Whenever AGONY Hub is minimized, hidden behind another window, or a game is launched into fullscreen mode, the engine automatically pauses to guarantee zero interference with game performance.

AGONY Hub respects accessibility preferences and provides a 1-click restore path for appearance settings.

1. Reduced Motion:

In Settings → Appearance & Animation, check Reduced Motion (#reduced-motion-toggle). This immediately:

• Disables animated CSS gradients and button hover transforms.
• Pauses all Atmosphere background particles.
• Sets modal and drawer transition times to 0 ms.

2. Restoring Default Appearance:

To reset custom theme colors back to factory defaults:

1. Open Settings and click Open Theme Library (#settings-open-theme-library).
2. Click Reset to Default (#btn-reset-theme-default).
3. AGONY Hub restores the default Obsidian Void palette (deep charcoal background, electric violet accents, and default typography).

AGONY Hub does not require Spotify developer accounts, OAuth callback servers, or personal API tokens for everyday media controls. It connects directly to the operating system's native media session.

How Native Controls Work:

• Windows System Media Transport Controls (SMTC): AGONY Hub hooks into Windows SMTC to receive real-time track metadata (Song Title, Artist, Album) and dispatch Play, Pause, Next Track, and Previous Track commands.
• Windows Core Audio (WASAPI): Volume adjustments and mute toggles communicate with the Windows Core Audio engine to control Spotify's per-process audio session directly.
• Universal Spotify Support: Works out-of-the-box for both Spotify Free and Spotify Premium without needing any API keys.

Checking Spotify in Settings:

Open Settings → Spotify Media Integration (Per-PC Configuration):

• Local SMTC & WASAPI badge verifies native session readiness.
• Click Open Spotify (#settings-spotify-launch-btn) to start the desktop app.
• Click Check Status (#settings-spotify-refresh-btn) to re-query the active media session.

AGONY Hub Settings • Spotify Media Integration Card Windows DPAPI • SMTC

Figure 4.1: Settings view showing verified Spotify Media Integration card and native controls.

In Settings → Spotify Media Integration, clicking Custom Connection… (#settings-spotify-config-btn) opens the Spotify Per-User Connection dialog (#spotify-config-modal).

Verified Dialog Fields (What Actually Exists):

Inspecting the actual application source code confirms only two optional fields exist:

• Custom Spotify Client ID (Optional) (#spotify-client-id-input): Accepts up to an 80-character string (e.g. your personal 32-character Spotify Developer App ID).
• Account Display Name or Tag (Optional) (#spotify-username-input): A local display tag for this PC profile.

DPAPI Storage & Disconnect:

Clicking Save to DPAPI encrypts the input with your Windows user account SID and writes it to %APPDATA%\AGONY Hub\spotify-auth.dat. Click Clear Credentials or Disconnect / Reset (#settings-spotify-disconnect-btn) to delete the credential file.

AGONY Hub bridges with WAND (and WeMod) to orchestrate modded game launches and export matching visual themes.

1. Enabling WAND in Settings:

In Settings → Integrations, check Enable WAND Integration (#toggle-wand-enabled). This unlocks:

• The WAND tab in the topbar navigation.
• The WAND launch mode option inside Game Details modals.
• The Open WAND Control Center button.

2. Inspecting Availability & Locating Executables:

The WAND Availability & Diagnostics row reports one of four states:

• Ready: Wand.exe or WeMod.exe verified on disk in standard paths or custom path.
• Not detected: Not found in standard directories (%LOCALAPPDATA%\Wand, %LOCALAPPDATA%\WeMod, Program Files). Click Locate WAND… (#settings-wand-locate-btn) to manually browse to the executable.
• Disabled: Toggle is off in Settings.
• Error: Path exists but is inaccessible.

AGONY Hub • WAND Control Center Dialog Modded Profiles • Visual Scripts

Figure 5.1: WAND Control Center dialog showing profile picker, dual accents, and script preview.

3. Visual-Only Theme Scripts:

In the WAND Control Center (#wand-modal), AGONY Hub provides a visual script generator for the Wand-Enhancer script loader:

• Configures primary (#wand-accent-1) and secondary (#wand-accent-2) theme colors.
• Click Export Theme to write agony-wand-theme.js.
• Strict Limitation: Generated scripts are visual CSS enhancements only. They do not alter game trainers, accounts, subscriptions, or network requests.

AGONY Hub v1.0.0 features a safe, transactional updater that guards active gameplay sessions.

1. Verifying Product Version:

Open Settings → Platform & Data. The Product Version displays v1.0.0 (#settings-product-version).

2. Checking for Updates:

Click Check for Updates (#btn-check-updates). If you are on the latest release, it confirms "AGONY Hub is up to date (v1.0.0)".

3. Active Session Guard:

If an update is downloaded while you are playing, AGONY Hub blocks installation while active game sessions are running. Once you finish playing and exit your game, the Restart & Update (#btn-install-update) button unlocks safely.

AGONY Hub Settings • Product Version & Automatic Updates v1.0.0 Stable Feed

Figure 6.1: Verified Settings Platform & Data section displaying official release v1.0.0.

AGONY Hub stores user configuration cleanly in your personal Windows roaming application directory:
%APPDATA%\AGONY Hub

1. Core Files Overview:

• library.json: Contains all your imported game titles, paths, playtime, and launch configs.
• settings.json: Stores UI preferences, card density, themes, and toggles.
• license.dat: DPAPI-encrypted 72-hour cryptographic lease.
• app.log: Redacted diagnostic operational log.

2. How to Reset Settings Safely:

1. Close AGONY Hub.
2. Press Win + R, type %APPDATA%\AGONY Hub, and press Enter.
3. Delete only settings.json. Your games in library.json and licensing leases remain completely safe.
4. Relaunch AGONY Hub. It will regenerate clean default settings while keeping all your games intact.

3. Diagnostic Logs (`app.log`):

AGONY Hub writes operational telemetry to %APPDATA%\AGONY Hub\app.log (rotating to app.log.old when exceeding 512 KB). The built-in logger automatically redacts user profile paths (C:\Users\<username> → %USERPROFILE%) and masks API tokens.

To avoid confusion, AGONY Hub maintains an explicit audit of required vs. zero-key integrations:

By default, AGONY Hub downloads game cover art from the Steam Store CDN without any API key. If you wish to search SteamGridDB's community repository of custom portrait covers, wide banners, and logos, you can configure an optional SteamGridDB API key.

Step-by-Step Configuration:

1. Obtain an API Key: Log into steamgriddb.com, navigate to your profile preferences → API, and generate an API key (e.g. sgdb_your_key_here).
2. Open Settings: In AGONY Hub, click Settings and scroll to Online Artwork Provider (SteamGridDB).
3. Enter & Test: Paste your key into the password field (#steamgriddb-key-input). Click Test Connection (#btn-steamgriddb-test).
4. Save Key: Once verified, click Save Key (#btn-steamgriddb-save).

AGONY Hub is engineered around strict local data ownership and zero telemetry tracking.

1. Windows DPAPI Encryption:

All sensitive local desktop credentials (including license.dat, spotify-auth.dat, and your SteamGridDB key) are protected using the Windows Data Protection API (DPAPI). They are tied directly to your Windows User SID and cannot be decrypted by unauthorized users or copied to another machine.

2. Safe Issue Reporting Guidelines:

• NEVER share passwords or tokens: AGONY Hub developers and support representatives will never ask you for passwords, session tokens, or private keys.
• Built-in Log Redaction: When submitting an operational log from %APPDATA%\AGONY Hub\app.log, the logger automatically masks user profile directories and hexadecimal tokens.
• Zero Telemetry & Zero Ads: AGONY Hub does not include tracking analytics, telemetry beacons, or advertising injectors.