Implement async preload download with per-file progress callbacks

[Cryotechnic]

Main Goal

Implement robust plugin-based preload, install, and update workflows with per-file progress tracking, proper exception safety across P/Invoke boundaries, and full IGameInstallManager compliance.

This pull request introduces significant improvements to the plugin-based game installation system, with a focus on adding robust per-file progress tracking and enhancing exception safety across reverse P/Invoke boundaries.

PR Status :

• Overall Status : Done
• Commits : Done
• Synced to base (Collapse:main) : Yes
• Build status : OK
• Crashing : No
• Bug found caused by PR : 0

Templates

Changelog Prefixes

  **[New]**
  **[Imp]**
  **[Fix]**
  **[Loc]**
  **[Doc]**

Key changes include:

Per-file Progress Tracking and Plugin Integration

• [New] Added support for per-file progress callbacks in PluginGameInstallWrapper, enabling more granular progress reporting during game installation and download. This includes defining a new delegate, registering/unregistering the callback with the plugin, and updating progress fields accordingly. [1]], [2]], [3]], [4]], [5]])
• [New] Implemented new methods in PluginInfo to register and unregister the per-file progress callback with the plugin via exported functions, with error handling and logging. ([CollapseLauncher/Classes/Plugins/PluginInfo.csR332-R368])
• [Imp] Added guard in TryRegisterPerFileProgressCallback to prevent leaking a GCHandle if the method is called more than once without a matching unregister.
• [Imp] Status.IsIncludePerFileIndicator is now set to _hasPerFileProgress after callback registration, so the UI correctly shows or hides the per-file progress indicator based on plugin capability.

Exception Handling and Stability

• [Imp] Wrapped all reverse P/Invoke callbacks (UpdateProgressCallback, UpdateStatusCallback, and the new per-file progress callback) in try/catch blocks to prevent unhandled exceptions from causing FailFast crashes, and added logging for swallowed exceptions. [1]], [2]], [3]], [4]])
• [Fix] StartPackageDownload now rethrows general exceptions after logging and Sentry reporting, preventing silent failures that would cause the verify→install pipeline to proceed with incomplete files.
• [Fix] Added general catch (Exception) block to StartPackageInstallation with Sentry reporting and rethrow, matching StartPackageDownload's error-handling pattern.
• [Fix] IsPreloadCompleted now propagates OperationCanceledException instead of swallowing it as false, making cancellation distinguishable from "not completed".
• [Fix] Status.IsCompleted is now only set to true on successful completion in both StartPackageDownload and StartPackageInstallation, tracked via a bool isSuccess flag. Previously it was set unconditionally in finally, making failures appear as completions.

Download and Installation Workflow Improvements

• [Imp] Refactored StartPackageDownload and StartPackageInstallation to integrate per-file progress registration/unregistration and to provide detailed logging and status updates throughout the process. [1]], [2]])
• [Imp] Improved fallback logic for progress reporting when per-file progress is not available, ensuring backward compatibility with older plugins. ([CollapseLauncher/Classes/Plugins/PluginGameInstallWrapper.csL298-R452])

Functional Enhancements

• [New] Implemented the IsPreloadCompleted method to accurately check if a preload download is complete by querying the plugin for total and downloaded sizes, with error handling. ([CollapseLauncher/Classes/Plugins/PluginGameInstallWrapper.csL415-R598])
• [New] Implemented UpdateCompletenessStatus to manage IsRunning/IsCompleted/IsCanceled state, progress indeterminate flags, and Discord presence updates, matching the InstallManagerBase convention.
• [New] Implemented CleanUpGameFiles to scan and remove residual temp/staging files under {GameDirPath}\TempPath\, with support for the FileCleanupPage dialog UI or direct deletion.
• [Fix] Fixed Locale.Lang → Locale.Current.Lang for all localization string accesses in UpdateStatusCallback, since Lang is an instance property on the Locale singleton.

Dependency Updates

• Updated the Microsoft.NET.ILLink.Tasks NuGet package from version 10.0.4 to 10.0.5 across multiple projects. [1]], [2]], [3]], [4]], [5]])
• Added Microsoft.NETFramework.ReferenceAssemblies version 1.0.3 as a new dependency in Hi3Helper.TaskScheduler. ([Hi3Helper.TaskScheduler/packages.lock.jsonR20-R28])

Miscellaneous

• [Loc] Minor language improvement in the FFmpeg installation lock message in en_US.json. ([Hi3Helper.Core/Lang/en_US.jsonL563-R563])

[Copilot]

Pull request overview

This PR enhances the plugin-based install/preload workflow by adding per-file progress reporting support (via a new reverse P/Invoke callback), improving callback exception safety across the native boundary, and updating a few dependencies/localized strings.

Changes:

• Add per-file progress callback registration/unregistration to the plugin wrapper and wire it into download/install progress reporting.
• Guard reverse P/Invoke callbacks with try/catch to prevent FailFast crashes from unhandled exceptions.
• Update dependencies / lockfiles and adjust an English UI string.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
Hi3Helper.TaskScheduler/packages.lock.json	Adds Microsoft.NETFramework.ReferenceAssemblies to lockfile for build/reference resolution.
Hi3Helper.Core/Lang/en_US.json	Tweaks FFmpeg lock message wording.
CollapseLauncher/Classes/Plugins/PluginInfo.cs	Adds plugin export calls to set/unset the per-file progress callback.
CollapseLauncher/Classes/Plugins/PluginGameInstallWrapper.cs	Implements async preload download, registers per-file progress callback, and hardens reverse P/Invoke callbacks.

Comments suppressed due to low confidence (1)

CollapseLauncher/Classes/Plugins/PluginGameInstallWrapper.cs:399

• Same issue here: Status.IsCompleted = true is set in finally even when OperationCanceledException is caught/rethrown (so IsCanceled and IsCompleted can both become true). Align completion/cancel status updates with the ProgressBase pattern (completed only on success; cancelled sets IsCanceled and keeps IsCompleted false).

        catch (OperationCanceledException)
        {
            Status.IsCanceled = true;
            throw;
        }
        finally
        {
            UnregisterPerFileProgressCallback();
            Status.IsCompleted = true;
            IsRunning = false;
            UpdateStatus();
        }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[neon-nyan]

All the changes should be looking good. Only few minor improvements required before this can be merged.

[sentry]

Bug: The UpdateProgressCallback method lacks a null check for the delegateProgress parameter, which could cause a NullReferenceException if a null value is passed from the native P/Invoke boundary.
_{Severity: HIGH}

Suggested Fix

Add a null check at the beginning of the UpdateProgressCallback method. If the delegateProgress parameter is null, the method should return immediately to prevent a NullReferenceException. This would align its implementation with the safer pattern used in OnPerFileProgressCallback.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: CollapseLauncher/Classes/Plugins/PluginGameInstallWrapper.cs#L477-L481

Potential issue: In the `UpdateProgressCallback` method, the `delegateProgress`
parameter, which is passed by reference from a native P/Invoke boundary, is accessed
without a preceding null check. If the calling native plugin provides a null or invalid
pointer, attempting to access members of `delegateProgress` (e.g., `DownloadedBytes`)
will result in a `NullReferenceException`. This violates the method's documented
contract that it "Must never throw," which can lead to an unhandled exception and cause
the application to crash.

[neon-nyan]