chore: Update documentation and version to v0.1.5, add per-file install progress feature

Author: Cryotechnic

README.md

@@ -11,9 +11,9 @@ Make sure that your code is **as reflection-free** as possible, as the code is e
 # What's Included?
 This Core Library includes various APIs to make the plugin development faster, without needing to implement the entire functions from scratch. Here's a list of what's included currently:
 
-### V1 (v0.1.4.0) Implementation Standard
+### V1 (v0.1.5.0) Implementation Standard
 
-This repository follows the V1 implementation standard (current library version: ``v0.1.4.0``). The standard collects base API contracts, COM interop helpers, marshallers and small utility primitives that plugin authors and the launcher can rely on.
+This repository follows the V1 implementation standard (current library version: ``v0.1.5.0``). The standard collects base API contracts, COM interop helpers, marshallers and small utility primitives that plugin authors and the launcher can rely on.
 
 > [!WARNING] 
 > The API contracts and implementations are still under development, so expect some breaking changes in the future.
@@ -46,6 +46,7 @@ This repository follows the V1 implementation standard (current library version:
     * v0.1-update2 ([source](https://github.com/CollapseLauncher/Hi3Helper.Plugin.Core/blob/main/SharedStatic.V1Ext_Update2.cs)): ``GetCurrentDiscordPresenceInfo``
     * v0.1-update3 ([source](https://github.com/CollapseLauncher/Hi3Helper.Plugin.Core/blob/main/SharedStatic.V1Ext_Update3.cs)): ``StartResizableWindowHookAsync``
     * v0.1-update4 ([source](https://github.com/CollapseLauncher/Hi3Helper.Plugin.Core/blob/main/SharedStatic.V1Ext_Update4.cs)): ``RegisterSpeedThrottlerService``
+    * v0.1-update5 ([source](https://github.com/CollapseLauncher/Hi3Helper.Plugin.Core/blob/main/SharedStatic.V1Ext_Update5.cs)): ``SetPerFileProgressCallback``
 
 * COM-API Interfaces/Contracts
   * [``IFree``](https://github.com/CollapseLauncher/Hi3Helper.Plugin.Core/blob/main/IFree.cs)

SharedStatic.cs

@@ -103,7 +103,7 @@ static unsafe SharedStatic()
     internal static string?                         ProxyPassword;
 
     public static string               PluginLocaleCode       { get; internal set; } = "en-us";
-    public static readonly GameVersion LibraryStandardVersion = new(0, 1, 4, 0);
+    public static readonly GameVersion LibraryStandardVersion = new(0, 1, 5, 0);
     public static readonly ILogger     InstanceLogger         = new SharedLogger();
 
 #if DEBUG

docs/advanced.md

@@ -6,6 +6,7 @@
 2. [Proxy settings](#2-proxy-settings)
 3. [Discord Rich Presence](#3-discord-rich-presence)
 4. [Multi-region plugins](#4-multi-region-plugins)
+5. [Per-file install progress](#5-per-file-install-progress)
 
 ---
 
@@ -251,3 +252,37 @@ public partial class MySeaPresetConfig : PluginPresetConfigBase
 - **`ProfileName` vs `ZoneName`** — `ZoneName` is the short display label in the launcher UI. `ProfileName` is used as an internal grouping key; it can be the same as `ZoneName`.
 - **Region ordering** — the launcher displays regions in the order the plugin returns them (index 0 first). Put the most common region first.
 - **Locale handling** — `SharedStatic.PluginLocaleCode` is set by the launcher via the `SetPluginCurrentLocale` export. Both preset configs read the same `PluginLocaleCode`, so API calls for different regions will automatically use the user's selected language.
+
+---
+
+## 5. Per-file install progress
+
+The launcher can receive per-file download progress from the plugin via the `v0.1-update5` extension export `SetPerFileProgressCallback`. This lets the launcher display fine-grained progress for each individual file being downloaded, rather than just the aggregate bytes.
+
+**No extra setup is required.** The export is automatically registered by `SharedStaticV1Ext<T>`. If the launcher supports it, it will call `SetPerFileProgressCallback` with a function pointer after loading the plugin. If the launcher does not support it, the callback is never set and calls to `InvokePerFileProgress` are no-ops.
+
+### Reporting progress from your installer
+
+Call `SharedStaticV1Ext.InvokePerFileProgress` each time you have a new byte count for the current file:
+
+```csharp
+using Hi3Helper.Plugin.Core;
+
+// Inside your download loop, after each chunk written:
+InvokePerFileProgress(perFileDownloadedBytes, perFileTotalBytes);
+```
+
+The helper is null-checked internally — it is always safe to call regardless of whether the launcher has registered a callback.
+
+### `InstallPerFileProgress` struct layout
+
+```
+Offset  Field                   Type    Description
+ 00–08  PerFileDownloadedBytes  long    Bytes downloaded so far for this file
+ 08–16  PerFileTotalBytes       long    Total size of this file in bytes
+```
+
+### Launcher-side behaviour
+
+- If the plugin exports `SetPerFileProgressCallback`, Collapse registers its handler on startup and shows per-file progress in the install UI.
+- If the plugin **does not** export the callback (i.e. older plugin versions), Collapse falls back to mirroring the aggregate `InstallProgressDelegate` as an approximation of per-file progress.

docs/introduction.md

@@ -38,7 +38,15 @@ Plugin.dll (NativeAOT)
 
 ## API standard versioning
 
-The current API standard version is **v0.1.4**. All plugins must implement at minimum the **v0.1 core** exports. Optional feature sets are versioned as update packages (`v0.1-update1`, `v0.1-update2`, etc.) and are handled automatically by `SharedStaticV1Ext<T>`.
+The current API standard version is **v0.1.5**. All plugins must implement at minimum the **v0.1 core** exports. Optional feature sets are versioned as update packages (`v0.1-update1`, `v0.1-update2`, etc.) and are handled automatically by `SharedStaticV1Ext<T>`.
+
+| Update | Export(s) added | Description |
+|--------|----------------|-------------|
+| v0.1-update1 | `LaunchGameFromGameManagerAsync`, `IsGameRunning`, `WaitRunningGameAsync`, `KillRunningGame`, `GetPluginUpdateCdnList`, `SetDnsResolverCallbackAsync` | Game launch/runtime management, async DNS resolver, CDN self-update |
+| v0.1-update2 | `GetCurrentDiscordPresenceInfo` | Discord Rich Presence |
+| v0.1-update3 | `StartResizableWindowHookAsync` | Resizable window hook |
+| v0.1-update4 | `RegisterSpeedThrottlerService` | Download speed throttling |
+| v0.1-update5 | `SetPerFileProgressCallback` | Per-file install/download progress reporting |
 
 ## Next steps
 

index.md

@@ -11,7 +11,7 @@ _layout: landing
 - **Full NativeAOT support** — designed to be compiled with .NET NativeAOT; reflection-free when targeting `MANUALCOM`/`USELIGHTWEIGHTJSONPARSER` configurations
 - **COM interop via `System.Runtime.InteropServices.Marshalling`** — no custom COM registration; the launcher discovers everything through a single `GetApiExport` entry point
 - **Batteries-included utilities** — pre-configured `HttpClient` builder with automatic proxy and DNS resolver integration, retry-able download streams, speed limiting, and unmanaged memory helpers
-- **Versioned extension API** — optional feature sets (`v0.1-update1` through `v0.1-update4`) for game launch, Discord Rich Presence, resizable-window hook, and download throttling are all opt-in
+- **Versioned extension API** — optional feature sets (`v0.1-update1` through `v0.1-update5`) for game launch, Discord Rich Presence, resizable-window hook, download throttling, and per-file install progress are all opt-in
 
 ## Getting started