Overview

Vortex's Install/Download Managers have been designed to run downloads and installations sequentially, this caused several core limitations and pain points in Vortex's download and installation pipeline, especially for large mod collections and high-concurrency scenarios. The main problems targeted were:

• Coupling of downloads and installations: Previously, downloads were tightly bound to installation completion, causing phase boundaries to block further downloads and leading to idle time and poor throughput.
• Phase gating and deployment reliability: Installers could advance phases before all deployments were confirmed, resulting in missed installs or stalled final phases.
• Incomplete archive installation: Installs sometimes started before downloads were fully finalized, risking corruption or partial mod installs.
• Game ID confusion: Path and metadata lookups often used Nexus domain IDs instead of internal Vortex game IDs, causing misrouting and 'not found' errors.
• UI and performance bottlenecks: Heavy download/install activity led to UI stutter and slow state updates due to blocking actions and unbatched progress dispatches.
• Error handling and recovery: Network errors, paused downloads, and race conditions were not robustly handled, leading to stuck or lost downloads and installs.

The aim of this piece of work is to decouple downloads from installs, enforce robust phase and deploy gating, ensure readiness before installation, normalize game ID usage, and improve concurrency, error recovery, and UI responsiveness throughout the mod management workflow.

Download Pipeline Revamp

• Queue tick engine: per-second ticks, starvation detection, better slot management.
• Raised concurrency limits (default: 10 downloads, 5 installations).
• Automatic resume/retry for paused or errored downloads.
• Non-blocking download finalization and metadata lookups.
• GraphQL-based metadata/requests and caching for download URLs.
• Early/parallelized API calls for metadata.

Install Pipeline Rework

• Decoupled downloads from installations; installs are phase-gated per collection/source mod.
• Deployments scheduled per phase when installers settle; next phases wait for previous deploy confirmation.
• Fixed off-by-one phase gating (final phase stalling) and added debug helpers/logs.
• Safer readiness checks to avoid installing missing/incomplete archives.
• Concurrent mod removal and improved dependency graphing and install flow.
• Improved instruction processing during extraction phase, ~4 times faster.

Internal Game ID Normalization

• Systematic conversion of Nexus domain IDs to internal Vortex game IDs in path lookups, resume logic, and UI interactions.
• Fixes applied across DownloadView, observer/handlers, mod management, and Nexus integration.

Performance and UX Quality

• Batched progress state updates to reduce dispatch churn.
• Deferred expensive Redux/UI actions to lower stutter during heavy download/install activity.
• Faster profile sanitization at startup.
• Option to remove invalid downloads on startup.
• Silent notifications are not displayed but still processed.

Stability and Error Handling

• Improved handling of temporary network errors and differentiating “already downloaded” states.
• Consolidated MD5 handling, switched to native md5 module, and now compute via API on finalization.
• Hardened sandboxing and IPC interactions; fixed several FOMOD installer edge cases and concurrency issues.
• Fixed race conditions around metadata responses and move operations.

Notable Fixes and Features

• InstallManager: Decoupled download/install, per-phase gating, deploy-on-settle, deployedPhases gating, debug helpers, normalized game ID usage.
• DownloadManager/Observer: Queue tick engine, starvation detection, improved restart/resume, non-blocking finalization/metadata flows, batching/caching.
• Nexus Integration: GraphQL for downloads, improved attribute extractor timeouts, reduced redundant domain conversion.
• FOMOD Installer: More robust concurrent installs, prevent running steps when none exist, allow multiple sockets per instance.
• Utilities/Infra: ConcurrencyLimiter can be reset, early UV thread pool sizing, updated dependencies, build/test fixes.

Impacted Areas

• Core: src/extensions/download_management/*, src/extensions/mod_management/*, src/util/ConcurrencyLimiter.ts, src/util/ExtensionManager.ts
• Integrations: src/extensions/nexus_integration/*
• FOMOD: src/extensions/installer_fomod/* including the fomod-installer dependency
• modmetadata-db: simplified fileHashes query and optimized responsiveness
• node-nexus-api: reduced quota and added logging to the fileHashes query

Behavior Changes

• Downloads can run ahead of installs; installs progress per phase only after deployments of previous phases are confirmed.
• Faster, more responsive UI during heavy download/install operations due to deferred/batched state updates.
• More reliable resume/retry behavior for downloads on transient errors.
• System-wide use of internal game IDs for path-sensitive operations reduces misrouting and “not found” errors.

Risks/Compatibility

• Increased concurrency and non-blocking behavior can surface race conditions in extensions not adapted to the new flow.
• Phase/deploy gating logic changes could impact custom installers/scripts expecting old coupling.
• GraphQL and md5 native changes depend on environment correctness - the metadata cache might have to be "popped".

Suggested collections to test with:

• Gate To Sovngarde - SSE; has 2 phases, should deploy at 99% before installing the last mod in the collection, then deploy again when it reaches 100% (Should take 2 hours at most on a 500Mbps connection)
• Aesthetic Valley | Witchcore - SDV; has 4 phases, phase 1 will install SMAPI - depending on which downloads were completed, the installation might appear to stall - it's not, it will kick off as soon as it identifies phase 2 downloads.
• SVE + Grandpa's Farm - SDV; has a single phase and should download and install almost immediately