API reference

C ABI exports

Collapse resolves exports from the plugin DLL by exact name using NativeLibrary.TryGetExport. All calling conventions are unmanaged[Cdecl].

Required exports

Collapse refuses to load any plugin that is missing one or more of these four exports.

GetPluginStandardVersion

Returns a pointer to the plugin SDK standard version that this plugin was compiled against.

GameVersion* GetPluginStandardVersion(void)

Returns — Pointer to a statically allocated GameVersion struct. Must remain valid for the lifetime of the process. Collapse uses this value for future compatibility negotiation.C# signature

[UnmanagedCallersOnly(EntryPoint = "GetPluginStandardVersion", CallConvs = [typeof(CallConvCdecl)])]
public static unsafe GameVersion* GetPluginStandardVersion()

Notes — The returned pointer must not point to stack memory. Use a static field.

GetPluginVersion

Returns a pointer to the plugin’s own release version.

GameVersion* GetPluginVersion(void)

Returns — Pointer to a statically allocated GameVersion struct. This version is compared against the version in manifest.json during update checks.C# signature

[UnmanagedCallersOnly(EntryPoint = "GetPluginVersion", CallConvs = [typeof(CallConvCdecl)])]
public static unsafe GameVersion* GetPluginVersion()

GetPlugin

Returns the plugin’s main COM object pointer. Collapse marshals this to an IPlugin interface.

void* GetPlugin(void)

Returns — Non-null IUnknown-compatible COM pointer implementing IPlugin. Returning null causes a NullReferenceException and the plugin load is aborted.C# signature

[UnmanagedCallersOnly(EntryPoint = "GetPlugin", CallConvs = [typeof(CallConvCdecl)])]
public static unsafe void* GetPlugin()

Notes — Use ComInterfaceMarshaller<IPlugin>.ConvertToUnmanaged(instance) to obtain the correct pointer from a managed IPlugin implementation.

SetLoggerCallback

Injects a logging callback from Collapse into the plugin. The plugin must use this callback to emit log lines.

void SetLoggerCallback(nint callback)

Parameters

callback — Function pointer of type void(LogLevel*, EventId*, char*, int). When Collapse passes nint.Zero, the callback must be cleared (this happens on plugin disposal).

Callback signature

// callback(LogLevel* logLevel, EventId* eventId, char* messageBuffer, int messageLength)
delegate* unmanaged[Cdecl]<LogLevel*, EventId*, char*, int, void>

C# signature

[UnmanagedCallersOnly(EntryPoint = "SetLoggerCallback", CallConvs = [typeof(CallConvCdecl)])]
public static void SetLoggerCallback(nint callbackPtr)

Notes — The delegate must be pinned or stored in a field with process lifetime to prevent garbage collection while the callback is registered.

Optional exports

These exports are resolved with TryGetExport and are silently skipped if absent.

FreePlugin

Graceful teardown before the DLL is unloaded. Collapse calls this in preference to calling IPlugin.Free() directly.

void FreePlugin(void)

Notes — If not present, Collapse falls back to calling Instance?.Free() on the IPlugin COM object. Implementing FreePlugin is strongly recommended because it gives you a clean shutdown point before NativeLibrary.Free is called.

GetPluginUpdateCdnList

Provides a list of CDN base URLs that Collapse uses to fetch manifest.json during managed update checks.

void GetPluginUpdateCdnList(int* count, nint* urlArrayPtr)

Parameters

count — Written with the number of URLs in the array.
urlArrayPtr — Written with a pointer to an array of count UTF-16 string pointers (ushort**). Each string is freed by Collapse using Utf16StringMarshaller.Free after reading.

C# signature

[UnmanagedCallersOnly(EntryPoint = "GetPluginUpdateCdnList", CallConvs = [typeof(CallConvCdecl)])]
public static unsafe void GetPluginUpdateCdnList(out int count, out nint urlArrayPtr)

Notes — If both count is 0 and urlArrayPtr is nint.Zero, managed update checking is skipped for this plugin. Collapse randomises the URL list before attempting each CDN.

SetDnsResolverCallback

Injects a synchronous DNS resolver so the plugin can share Collapse’s custom DNS server configuration.

void SetDnsResolverCallback(nint callback)

Callback signature — The callback receives a null-terminated UTF-16 hostname and writes resolved IP address strings into a caller-provided buffer:

void callback(char* hostname, char* ipWriteBuffer, int bufferLength, int* resolvedCount)

Notes — Pass nint.Zero to clear the callback (called on plugin disposal).

SetDnsResolverCallbackAsync

Asynchronous variant of the DNS resolver callback, using a task pointer pattern.

void SetDnsResolverCallbackAsync(nint callback)

Callback signature

// Returns a task pointer. cancelCallbackP is written with a void(void) cancel function pointer.
nint callback(char* hostname, int hostnameLength, void** cancelCallbackP)

Notes — The returned nint is a task handle compatible with Collapse’s AsTask<nint> pattern. Pass nint.Zero to deregister.

RegisterSpeedThrottlerService

Registers the plugin with Collapse’s global download speed throttler. Called automatically when the user enables the speed limiter in Settings.

HResult RegisterSpeedThrottlerService(nint addBytesCallback, nint getThrottleCallback)

Parameters

addBytesCallback — Pointer to SpeedLimiterService.AddBytesOrWaitAsyncDelegatePtr. Pass to your HTTP download loop to report downloaded bytes and wait if the throttle limit is reached.
getThrottleCallback — Pointer to SpeedLimiterService.GetSharedThrottleBytesDelegatePtr. Used to query the current throttle byte limit.

Returns — HResult.S_OK on success. Any failure HRESULT is logged as an error.Notes — Collapse passes nint.Zero for both parameters to deregister the throttler (e.g., when the user disables the speed limiter).

COM interfaces

All interfaces are defined in Hi3Helper.Plugin.Core. Implement them in your plugin and expose them through the C ABI exports.

IPlugin

The root interface returned by GetPlugin. Collapse calls these methods immediately after loading the DLL.

Method	Description
`GetPluginName(out string? name)`	Returns the display name shown in the Plugin Manager.
`GetPluginDescription(out string? description)`	Returns the short description shown in the Plugin Manager.
`GetPluginAuthor(out string? author)`	Returns the author name.
`GetPluginCreationDate(out DateTime* creationDate)`	Returns a pointer to a `DateTime` struct, or `null` to fall back to the manifest date.
`GetPresetConfigCount(out int count)`	Returns the number of `IPluginPresetConfig` instances this plugin exposes. Must be ≥ 1.
`GetPresetConfig(int index, out IPluginPresetConfig presetConfig)`	Returns the preset config at `index`. Called for each index from `0` to `count - 1`.
`GetPluginSelfUpdater(out IPluginSelfUpdate? selfUpdater)`	Returns the plugin’s self-updater, or `null` if the plugin handles updates via CDN manifest only.
`SetPluginLocaleId(string localeId)`	Called when the launcher UI language changes. Use to localise plugin-supplied strings.
`Free()`	COM-level release. Called if `FreePlugin` export is not present.
`RegisterCancelToken(CancellationToken token) -> Guid`	Registers a managed cancellation token and returns a `Guid` handle for use in async plugin calls.

IPluginPresetConfig

Represents one game region. Collapse wraps each instance in a PluginPresetConfigWrapper and registers it as a PresetConfig in the metadata system. Mandatory methods

Method	Description
`InitAsync(Guid cancelToken, out nint asyncResult)`	Called once after construction. `asyncResult` must be a task handle that resolves to `int` (0 = success).
`comGet_GameManager(out IGameManager? gameManager)`	Returns the `IGameManager` for this region. Must not return `null`.
`comGet_LauncherApiMedia(out ILauncherApiMedia? media)`	Returns the `ILauncherApiMedia` instance. Must not return `null`.
`comGet_LauncherApiNews(out ILauncherApiNews? news)`	Returns the `ILauncherApiNews` instance. Must not return `null`.
`comGet_GameName(out string result)`	Game name used as the metadata key.
`comGet_ZoneName(out string result)`	Region/zone name used as the metadata key.
`comGet_ZoneFullName(out string result)`	Full display name (e.g., `"My Game — Global"`).
`comGet_ProfileName(out string result)`	Profile name used for constructing the default install path.
`comGet_ZoneDescription(out string result)`	Short zone description.
`comGet_GameExecutableName(out string result)`	Game executable file name (e.g., `"MyGame.exe"`).
`comGet_LauncherGameDirectoryName(out string result)`	Default game directory name under the launcher’s game folder.
`comGet_ReleaseChannel(out GameReleaseChannel result)`	Release channel: `Stable`, `OpenBeta`, or `ClosedBeta`.
`comGet_GameMainLanguage(out string result)`	Default language code (e.g., `"en-us"`).
`comGet_GameSupportedLanguagesCount(out int count)`	Number of supported languages.
`comGet_GameSupportedLanguages(int index, out string result)`	Language code at `index`.
`comGet_GameVendorName(out string result)`	Vendor/studio name string used for `GameVendorProp`.

Optional methods

Method	Description
`comGet_GameRegistryKeyName(out string? result)`	Registry key name for the game’s config, or `null`.
`comGet_GameLogFileName(out string? result)`	Game log file name, or `null`.
`comGet_GameAppDataPath(out string? result)`	Path to the game’s AppData directory, or `null`.
`comGet_ZoneLogoUrl(out string result)`	URL or base64-encoded logo image.
`comGet_ZonePosterUrl(out string result)`	URL or base64-encoded poster image.
`comGet_ZoneHomePageUrl(out string result)`	Official game home page URL.
`comGet_GameInstaller(out IGameInstaller? installer)`	Returns an `IGameInstaller` COM object, or `null` to disable plugin-driven installation.
`Free()`	COM-level release.

IGameManager

Drives game state detection, version reporting, path management, and config persistence. Collapse calls these methods through PluginGameVersionWrapper.

Method	Description
`SetGamePath(string path)`	Sets the game installation path.
`GetGamePath(out string? path)`	Returns the current game installation path.
`LoadConfig()`	Loads the game’s configuration from disk.
`SaveConfig()`	Persists the game’s configuration to disk.
`IsGameInstalled(out bool result)`	Returns `true` if the game is installed at the configured path.
`IsGameHasUpdate(out bool result)`	Returns `true` if a game update is available.
`IsGameHasPreload(out bool result)`	Returns `true` if a preload package is available.
`GetCurrentGameVersion(out GameVersion gameVersion)`	Returns the locally installed game version.
`GetApiGameVersion(out GameVersion gameVersion)`	Returns the latest game version from the API.
`GetApiPreloadGameVersion(out GameVersion gameVersion)`	Returns the preload game version from the API.
`SetCurrentGameVersion(GameVersion version)`	Writes the current installed version (called after install/update).
`FindExistingInstallPathAsync(in Guid cancelToken, out nint asyncResult)`	Searches for an existing installation and returns its path via a task handle.
`InitPluginComAsync(IPlugin plugin, CancellationToken token) -> Task`	Initializes the game manager. Called before any install/update operation.

ILauncherApiMedia

Supplies background images and logo overlays for the launcher home page.

Method	Description
`InitPluginComAsync(IPlugin plugin, CancellationToken token) -> Task`	Fetches remote media data. Called during `PluginLauncherApiWrapper.LoadAsync`.
`GetBackgroundEntries`	Property/method returning a span of `LauncherPathEntry` structs. Each entry contains a `Path` string (URL or base64 image data).
`GetLogoOverlayEntries`	Same structure as `GetBackgroundEntries` but for logo overlay images shown on top of backgrounds.
`Free()`	COM-level release.

Image data may be provided as a data: URI or raw base64 string. Collapse decodes and caches the embedded data automatically using ImageLoaderHelper.CopyToLocalIfBase64.

ILauncherApiNews

Supplies news articles, carousel banners, and social media links.

Method	Description
`InitPluginComAsync(IPlugin plugin, CancellationToken token) -> Task`	Fetches remote news data. Called during `PluginLauncherApiWrapper.LoadAsync`.
`GetNewsEntries`	Returns a span of `LauncherNewsEntry` structs with `Title`, `Url`, `PostDate`, `Description`, and `Type` (`Info`, `Notice`, or `Event`).
`GetCarouselEntries`	Returns a span of `LauncherCarouselEntry` structs with `ImageUrl`, `Description`, and `ClickUrl`.
`GetSocialMediaEntries`	Returns a span of `LauncherSocialMediaEntry` structs with icon paths, click URL, QR code data, and nested child links.
`Free()`	COM-level release.

IPluginSelfUpdate

Implements plugin self-updating. Return an instance from IPlugin.GetPluginSelfUpdater to enable the unmanaged update path. If you prefer the managed CDN path, return null and implement GetPluginUpdateCdnList instead.

Method	Description
`TryPerformUpdateAsync(string outputDir, bool checkOnly, ProgressDelegate? progress, Guid cancelToken, out nint asyncResult)`	Performs the update check (when `checkOnly = true`) or the full download (when `checkOnly = false`). `asyncResult` is a task handle that resolves to `nint` — either a raw `SelfUpdateReturnCode` enum value or a pointer to a `SelfUpdateReturnInfo` struct.

SelfUpdateReturnCode flags

Flag	Meaning
`Ok`	Operation completed without error.
`UpdateIsAvailable`	A newer version was found.
`UpdateSuccess`	Update downloaded successfully.
`Error`	An error occurred; the plugin should log details.

SelfUpdateReturnInfo struct fields

Field	Type	Description
`ReturnCode`	`SelfUpdateReturnCode`	Combination of flags.
`PluginVersion`	`GameVersion?`	Available version, if update found.
`StandardVersion`	`GameVersion?`	Standard version of the new release.
`Name`	`string?`	Plugin name from the new release.
`Author`	`string?`	Plugin author from the new release.
`Description`	`string?`	Plugin description from the new release.
`CreationDate`	`DateTimeOffset?`	Creation date of the new release.
`CompiledDate`	`DateTimeOffset?`	Compilation date of the new release.

IGameInstaller

Drives game installation and updates. Return from IPluginPresetConfig.comGet_GameInstaller. Optional — if null, Collapse disables the install/update UI for this region.

Method	Description
`InitPluginComAsync(IPlugin plugin, CancellationToken token) -> Task`	Initializes the installer before any operation.
`GetGameSizeAsync(GameInstallerKind kind, in Guid cancelToken, out nint asyncResult)`	Returns total bytes to download as `long` via task handle.
`GetGameDownloadedSizeAsync(GameInstallerKind kind, in Guid cancelToken, out nint asyncResult)`	Returns already-downloaded bytes as `long` via task handle.
`StartInstallAsync(InstallProgressDelegate progress, InstallProgressStateDelegate status, Guid cancelToken, out nint asyncResult)`	Runs the full installation.
`StartUpdateAsync(InstallProgressDelegate progress, InstallProgressStateDelegate status, Guid cancelToken, out nint asyncResult)`	Runs the update.
`Free()`	COM-level release.

Optionally, IGameInstaller can also implement IGameUninstaller:

Method	Description
`UninstallAsync(Guid cancelToken, out nint asyncResult)`	Removes the game from disk.

Get Started

Using Collapse

Advanced

Plugin Development

C ABI exports

Required exports

Optional exports

COM interfaces

IPlugin

IPluginPresetConfig

IGameManager

ILauncherApiMedia

ILauncherApiNews

IPluginSelfUpdate

IGameInstaller

Build docs developers (and LLMs) love

Get Started

Using Collapse

Advanced

Plugin Development

Documentation Index

​C ABI exports

​Required exports

​Optional exports

​COM interfaces

​IPlugin

​IPluginPresetConfig

​IGameManager

​ILauncherApiMedia

​ILauncherApiNews

​IPluginSelfUpdate

​IGameInstaller

Build docs developers (and LLMs) love

C ABI exports

Required exports

Optional exports

COM interfaces

IPlugin

IPluginPresetConfig

IGameManager

ILauncherApiMedia

ILauncherApiNews

IPluginSelfUpdate

IGameInstaller