@nexusmods/vortex-api 1.0.0 → 2.2.0-beta.1

package/README.md

@@ -0,0 +1,262 @@
+# Vortex API
+
+Type definitions for the [Vortex](https://www.nexusmods.com/about/vortex/) extension API.
+
+This package provides auto-generated typings that extensions can use to interact with Vortex - the mod manager by Nexus Mods.
+
+## Documentation
+
+For packaging and distributing extensions, see [Packaging extensions for Vortex](https://wiki.nexusmods.com/index.php/Packaging_extensions_for_Vortex).
+
+For API changes between versions, see the [Changelog](CHANGELOG.md).
+
+For a full list of events extensions can listen to or emit, see the [Events Reference](docs/EVENTS.md).
+
+For notable open-source extensions with advanced patterns, see the [Example Extensions](docs/EXAMPLES.md).
+
+## Installation
+
+```
+npm install vortex-api
+```
+
+`vortex-api` declares Vortex runtime packages (React, Redux, Bluebird, etc.) as `peerDependencies`. With pnpm, npm 7+, or Yarn Berry these are installed automatically - you don't need to add them to your own `devDependencies`. For details on migrating from earlier versions, see the [Migration Guide](docs/MIGRATION.md).
+
+## Extension structure
+
+A Vortex extension is a JavaScript module that exports an `init` function. The function receives an `IExtensionContext` object that provides access to the full API.
+
+`info.json`
+
+- `name` - the display name of your extension.
+- `author` - the extension author's name.
+- `version` - the version of your extension.
+- `description` - a short description of what your extension does.
+
+`index.js`
+
+- This is the main entry point of your extension.
+- Import Vortex API types using `import { types, util, selectors } from 'vortex-api'`
+- Must export a `default` function (or named `init`) that receives `IExtensionContext`.
+- Must bundle all external dependencies into the output.
+
+## App architecture
+
+#### Vortex is organized around a few core systems:
+
+- **Extensions** - modular plugins that add game support, UI pages, settings, and more. Extensions interact with Vortex through the `IExtensionContext` interface.
+- **State (Redux)** - all application state is managed through a Redux store. Extensions can register reducers and react to state changes.
+- **Profiles** - users can create multiple mod profiles per game, each with its own set of enabled mods and configuration.
+- **Mod Management** - handles mod installation, deployment (via symlinks or hardlinks), and conflict resolution.
+
+#### Through `IExtensionContext`, extensions can:
+
+- Register game support using `registerGame`.
+- Add main pages and dialog pages using `registerMainPage` and `registerDialog`.
+- Add mod installers using `registerInstaller` and `registerModType`.
+- Add action buttons and toolbar items using `registerAction`.
+- Add settings pages using `registerSettings`.
+- Access the Redux store via `context.api.getState()` and `context.api.store`.
+- Show notifications and dialogs via `context.api.sendNotification` and `context.api.showDialog`.
+
+#### Registering to lifecycle events
+
+Extensions can hook into the application lifecycle:
+
+```ts
+function init(context: IExtensionContext) {
+    // Called when the extension is loaded.
+    // Register your features here.
+
+    context.once(() => {
+        // Called after all extensions have been loaded.
+        // Safe to interact with other extensions here.
+    });
+}
+```
+
+## Game extensions
+
+The [`extensions/games/`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games) directory in the Vortex repository contains game support extensions that serve as practical examples. They range from simple to complex:
+
+#### Simple game support (~100 lines)
+
+A minimal game extension registers the game and tells Vortex where to find it. Only `id`, `name`, `executable`, `requiredFiles`, and `queryModPath` are required - everything else is optional:
+
+```ts
+function init(context: IExtensionContext) {
+    context.registerGame({
+        id: "mygame",
+        name: "My Game",
+        mergeMods: true,
+        logo: "gameart.jpg",
+        executable: () => "MyGame.exe",
+        requiredFiles: ["MyGame.exe"],
+        queryModPath: () => "Mods",
+        // Vortex will auto-discover the game across all supported stores
+        queryArgs: {
+            steam: [{ name: "My Game" }],
+            gog: [{ id: "1234567890" }],
+            xbox: [{ id: "PublisherName.MyGame" }],
+            epic: [{ id: "abc123def456" }],
+            registry: [{ id: "HKEY_LOCAL_MACHINE:Software\\MyGame:InstallPath" }],
+        },
+        // Environment variables set when launching the game executable
+        environment: {
+            SteamAPPId: "12345",
+        },
+        // Metadata used by Vortex and Nexus Mods integration
+        details: {
+            steamAppId: 12345, // numeric Steam app ID for API lookups
+            gogAppId: "1234567890", // GOG app ID
+            nexusPageId: "mygame", // the game's URL slug on nexusmods.com
+            hashFiles: [
+                // files used to identify the game version via hashing
+                "MyGame.exe",
+                path.join("Data", "Main.esm"),
+            ],
+        },
+    });
+
+    return true;
+}
+```
+
+See: [`game-skyrimse`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-skyrimse) for a full example with multi-store support, or [`game-darksouls`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-darksouls), [`game-grimrock`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-grimrock) for simpler cases.
+
+#### Custom installers
+
+Extensions can register installers to handle game-specific mod formats. The installer tests whether it can handle an archive, then returns file placement instructions:
+
+```ts
+context.registerInstaller("rimworld-mod", 50, testSupported, installContent);
+
+async function testSupported(files: string[]) {
+    const hasManifest = files.find((f) => path.basename(f) === "About.xml") !== undefined;
+    return { supported: hasManifest, requiredFiles: [] };
+}
+
+async function installContent(files: string[]) {
+    const instructions = files
+        .filter((f) => !f.endsWith(path.sep))
+        .map((f) => ({ type: "copy", source: f, destination: f }));
+    return { instructions };
+}
+```
+
+See: [`game-rimworld`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-rimworld), [`game-kenshi`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-kenshi), [`game-stardewvalley`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-stardewvalley), [`game-neverwinter-nights`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-neverwinter-nights) (file-extension-to-destination routing), [Cyberpunk 2077](https://github.com/E1337Kat/cyberpunk2077_ext_redux) (multi-type detection from a single archive), [Elden Ring](https://github.com/Senjay-id/eldenring-vortex-extension) (5 priority-based installers), [Ready Or Not](https://github.com/BeYkeRYkt/vortex_readyornot_extension) (type-specific test/install pairs)
+
+#### Custom mod types
+
+Games with multiple mod installation targets can register mod types so users can choose where files are deployed:
+
+```ts
+context.registerModType(
+    "bg3-loose",
+    25,
+    (gameId) => gameId === "baldursgate3",
+    () => path.join(modsPath, "Loose"),
+    (instructions) => Promise.resolve(isLooseMod(instructions)),
+    { name: "Loose Files" },
+);
+```
+
+See: [`game-baldursgate3`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-baldursgate3), [`game-stardewvalley`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-stardewvalley), [`game-nomanssky`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-nomanssky) (mod type migration between deprecated and current formats), [Oblivion Remastered](https://github.com/Nexus-Mods/game-oblivionremastered) (6 mod formats with architecture-aware paths)
+
+#### Load order management
+
+Games with strict plugin ordering can register a load order system:
+
+```ts
+context.registerLoadOrder({
+    gameId: GAME_ID,
+    deserializeLoadOrder: () => readCurrentOrder(),
+    serializeLoadOrder: (order) => writeOrder(order),
+    validate: (order) => checkForErrors(order),
+    usageInstructions: "Drag and drop to reorder plugins.",
+});
+```
+
+See: [`game-baldursgate3`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-baldursgate3), [`game-morrowind`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-morrowind) (load order with validation and collections support), [Bannerlord](https://github.com/BUTR/game-mount-and-blade2) (auto-sort on deploy), [Ready Or Not](https://github.com/BeYkeRYkt/vortex_readyornot_extension) (prefix-based filesystem ordering), [Starfield](https://github.com/Nexus-Mods/game-starfield) (conditional LOOT integration)
+
+#### Supported tools
+
+Extensions can bundle tool definitions so users can launch community tools (script extenders, body editors, modding utilities) directly from Vortex:
+
+```ts
+const tools: ITool[] = [
+  {
+    id: 'skse64',
+    name: 'Skyrim Script Extender 64',
+    executable: () => 'skse64_loader.exe',
+    requiredFiles: ['skse64_loader.exe'],
+    relative: true,
+    exclusive: true,
+    defaultPrimary: true,
+  },
+];
+
+context.registerGame({ ..., supportedTools: tools });
+```
+
+See: [`game-skyrimse`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-skyrimse), [`game-stardewvalley`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-stardewvalley), [`game-oblivion`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-oblivion)
+
+#### Event hooks
+
+Extensions can react to deployment, installation, and game mode changes:
+
+```ts
+context.once(() => {
+    context.api.onAsync("did-deploy", async (profileId, deployment) => {
+        // Called after mods are deployed - sync load order, write config, etc.
+    });
+
+    context.api.events.on("gamemode-activated", (gameId: string) => {
+        // Called when the user switches game mode.
+    });
+});
+```
+
+For a full list of available events, see the [Events Reference](docs/EVENTS.md).
+
+See: [`game-baldursgate3`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-baldursgate3), [`game-stardewvalley`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-stardewvalley), [`game-witcher3`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-witcher3) (extensive event-driven pipeline), [Oblivion Remastered](https://github.com/Nexus-Mods/game-oblivionremastered) (INI merge on `will-deploy`, Lua processing on `did-deploy`), [Elden Ring](https://github.com/Senjay-id/eldenring-vortex-extension) (auto-set primary tool on deploy)
+
+#### File merge support
+
+Extensions can register merge functions to combine files from multiple mods (e.g. XML config files):
+
+```ts
+context.registerMerge(
+    (game, discovery) => canMerge(game, discovery), // test: can this game merge?
+    (filePath, mergePath) => doMerge(filePath, mergePath), // perform the merge
+    "merge-id",
+);
+```
+
+See: [`game-dragonage`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-dragonage) (XML merge for AddIns.xml), [`game-witcher3`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-witcher3) (script merger tool integration), [Starfield](https://github.com/Nexus-Mods/game-starfield) (INI merge system)
+
+#### Multi-game registration
+
+A single extension can register multiple game variants:
+
+```ts
+function init(context: IExtensionContext) {
+  context.registerGame({ id: 'neverwinter', name: 'Neverwinter Nights', ... });
+  context.registerGame({ id: 'neverwinteree', name: 'Neverwinter Nights: Enhanced Edition', ... });
+  return true;
+}
+```
+
+See: [`game-neverwinter-nights`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-neverwinter-nights)
+
+## Example extensions
+
+For a curated list of notable open-source extensions with advanced patterns, see the [Example Extensions](docs/EXAMPLES.md).
+
+## Issues and requests
+
+For bugs and feature requests related to the API, please open an issue on the [Vortex repository](https://github.com/Nexus-Mods/Vortex/issues).
+
+## License
+
+[GPL-3.0](LICENSE.md)

package/bin/extractInfo.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+function transformName(input) {
+  return (
+    input.charAt(0).toUpperCase() +
+    input.substr(1).replace(/-([a-z])/g, (match, m1) => " " + m1.toUpperCase())
+  );
+}
+
+function getExtensionName(pkgInfo) {
+  if (pkgInfo.config && pkgInfo.config.game) {
+    return `Game: ${pkgInfo.config.game}`;
+  }
+  if (pkgInfo.config && pkgInfo.config.extensionName) {
+    return pkgInfo.config.extensionName;
+  }
+  return transformName(pkgInfo.name);
+}
+
+/**
+ * function intended to be run during build of an extension,
+ * extracting details about it from its package.json
+ * @param {string} extPath path to the extension
+ * @returns {import('vortex-api').types.IExtension} an extensionInfo object
+ */
+function extractExtensionInfo(extPath) {
+  const pkgInfo = JSON.parse(fs.readFileSync(path.join(extPath, "package.json")).toString());
+
+  return {
+    name: getExtensionName(pkgInfo),
+    namespace: pkgInfo.config?.namespace,
+    author: pkgInfo.author,
+    version: pkgInfo.version,
+    description: pkgInfo.description,
+    issueTrackerURL: pkgInfo.config?.issueTracker,
+  };
+}
+
+fs.writeFileSync(
+  path.join("dist", "info.json"),
+  JSON.stringify(extractExtensionInfo(process.cwd())),
+);

package/docs/EVENTS.md

@@ -0,0 +1,203 @@
+# Vortex Events Reference
+
+This document lists all events that extensions can listen to or emit through the Vortex API.
+
+## Event patterns
+
+Vortex uses two event mechanisms:
+
+```ts
+// Synchronous events - fire-and-forget
+context.api.events.on('event-name', (args) => { ... });
+context.api.events.emit('event-name', args);
+
+// Async events - handlers return promises, caller can await all handlers
+context.api.onAsync('event-name', async (args) => { ... });
+await context.api.emitAndAwait('event-name', args);
+```
+
+Register event handlers inside `context.once()` to ensure all extensions are loaded first.
+
+---
+
+## Game mode & profile
+
+| Event                 | Args                  | Description                            |
+| --------------------- | --------------------- | -------------------------------------- |
+| `gamemode-activated`  | `(gameId: string)`    | User switched to a different game mode |
+| `activate-game`       | `(gameId: string)`    | Request to activate a game             |
+| `profile-did-change`  | `(profileId: string)` | Profile has been switched              |
+| `profile-will-change` | -                     | About to switch profiles               |
+
+## Game discovery
+
+| Event                        | Args                                         | Description                                  |
+| ---------------------------- | -------------------------------------------- | -------------------------------------------- |
+| `discover-game`              | `(gameId: string)`                           | Async. Discover a specific game installation |
+| `discover-tools`             | `(gameId: string)`                           | Async. Discover tools for a game             |
+| `start-discovery`            | -                                            | Start full game discovery scan               |
+| `start-quick-discovery`      | `(cb?: (gameIds: string[]) => void)`         | Quick discovery of known games               |
+| `cancel-discovery`           | -                                            | Cancel ongoing discovery                     |
+| `refresh-game-info`          | `(gameId: string, cb: (err: Error) => void)` | Refresh cached info for a game               |
+| `manually-set-game-location` | `(gameId: string, cb: (err: Error) => void)` | Manually set game install path               |
+
+## Deployment
+
+| Event                | Args                                                        | Description                            |
+| -------------------- | ----------------------------------------------------------- | -------------------------------------- |
+| `will-deploy`        | `(profileId: string, deployment?: IDeploymentManifest)`     | Async. Before deployment begins        |
+| `did-deploy`         | `(profileId: string, deployment?: IDeploymentManifest)`     | Async. After deployment completes      |
+| `will-purge`         | `(profileId: string, lastDeployment?: IDeploymentManifest)` | Async. Before purge (un-deploy) begins |
+| `did-purge`          | `(profileId: string)`                                       | Async. After purge completes           |
+| `deploy-mods`        | `(profileId: string, cb?, ...)`                             | Request mod deployment                 |
+| `deploy-single-mod`  | `(gameId: string, modId: string, ...)`                      | Async. Deploy a single mod             |
+| `purge-mods`         | `(allowFallback: boolean, cb: (err: Error) => void)`        | Purge all deployed mods                |
+| `purge-mods-in-path` | `(gameId: string, modType: string, modPath: string)`        | Async. Purge mods in a specific path   |
+| `await-activation`   | `(cb: (err: Error) => void)`                                | Wait for current deployment to finish  |
+
+## Mod installation
+
+| Event                    | Args                                                    | Description                     |
+| ------------------------ | ------------------------------------------------------- | ------------------------------- |
+| `will-install-mod`       | `(gameId: string, archiveId: string, modId: string)`    | Async. Before mod installation  |
+| `did-install-mod`        | `(gameId: string, archiveId: string, modId: string)`    | After mod is installed          |
+| `start-install`          | `(archivePath: string, cb?: (err, id: string) => void)` | Start install from archive path |
+| `start-install-download` | `(downloadId: string, ...)`                             | Start install from a download   |
+| `create-mod`             | `(gameId: string, mod: IMod, cb: (err: Error) => void)` | Create a new mod entry          |
+| `mod-content-changed`    | -                                                       | Mod files on disk changed       |
+| `simulate-installer`     | -                                                       | Simulate mod installation       |
+
+## Mod removal
+
+| Event              | Args                                                              | Description                      |
+| ------------------ | ----------------------------------------------------------------- | -------------------------------- |
+| `will-remove-mod`  | `(gameId: string, modId: string, options?: IRemoveModOptions)`    | Async. Before single mod removal |
+| `did-remove-mod`   | `(gameId: string, modId: string, ...)`                            | Async. After single mod removal  |
+| `will-remove-mods` | `(gameId: string, modIds: string[], options?: IRemoveModOptions)` | Async. Before batch mod removal  |
+| `did-remove-mods`  | `(gameId: string, removedMods: IMod[])`                           | Async. After batch removal       |
+| `remove-mod`       | `(gameId: string, modId: string, ...)`                            | Request single mod removal       |
+| `remove-mods`      | `(gameId: string, modIds: string[], ...)`                         | Request batch mod removal        |
+
+## Mod state
+
+| Event                           | Args                                 | Description                                   |
+| ------------------------------- | ------------------------------------ | --------------------------------------------- |
+| `mod-enabled`                   | `(profileId: string, modId: string)` | A mod was enabled in a profile                |
+| `mods-enabled`                  | -                                    | One or more mods were enabled                 |
+| `did-enable-mods`               | -                                    | Async. Mods were enabled (load order trigger) |
+| `recalculate-modtype-conflicts` | -                                    | Recalculate mod type conflicts                |
+
+## Downloads
+
+| Event                     | Args                                                          | Description                                          |
+| ------------------------- | ------------------------------------------------------------- | ---------------------------------------------------- |
+| `start-download`          | `(urls, modInfo, fileName?, cb?, ...)`                        | Start downloading a file                             |
+| `start-download-url`      | `(url: string)`                                               | Start download from a direct URL                     |
+| `pause-download`          | `(downloadId, cb?)`                                           | Pause an active download                             |
+| `resume-download`         | `(downloadId, cb?, options?)`                                 | Resume a paused download                             |
+| `remove-download`         | `(downloadId, cb?, options?: IDownloadRemoveOptions)`         | Remove a download                                    |
+| `did-finish-download`     | `(downloadId: string, state: string)`                         | Download completed                                   |
+| `import-downloads`        | `([filePath], cb: (dlIds: string[]) => void)`                 | Import downloads from files                          |
+| `did-import-downloads`    | `(dlIds: string[], cb?: (err?: Error) => void)`               | Downloads were imported                              |
+| `did-move-downloads`      | -                                                             | Downloads folder was moved                           |
+| `will-move-downloads`     | -                                                             | Downloads folder is about to move                    |
+| `refresh-downloads`       | `(gameId: string, cb: (err) => void)`                         | Refresh download list                                |
+| `enable-download-watch`   | `(enabled: boolean)`                                          | Enable/disable download folder watching              |
+| `set-download-games`      | `(dlId: string, gameIds: string[], fromMetadata?: boolean)`   | Async. Assign game(s) to a download                  |
+| `filehash-calculated`     | `(filePath: string, md5Hash: string, fileSize: number)`       | File hash was computed                               |
+| `get-download-free-slots` | `(cb: (freeSlots: number) => void)`                           | Query available download slots                       |
+| `start-download-update`   | `(source, modId, fileId?, ...)`                               | Async. Start download update check                   |
+| `browse-for-download`     | `(navUrl: string, instructions: string, skippable?: boolean)` | Async. Open browser for download. Returns `string[]` |
+
+## Dependencies
+
+| Event                       | Args                                                                      | Description                          |
+| --------------------------- | ------------------------------------------------------------------------- | ------------------------------------ |
+| `install-dependencies`      | `(profileId: string, gameId: string, modIds: string[], silent?: boolean)` | Install mod dependencies             |
+| `install-recommendations`   | `(profileId: string, gameId: string, modIds: string[])`                   | Install recommended mods             |
+| `did-install-dependencies`  | -                                                                         | Dependencies were installed          |
+| `install-from-dependencies` | -                                                                         | Async. Install from dependency list  |
+| `cancel-dependency-install` | `(modId: string)`                                                         | Async. Cancel dependency install     |
+| `reset-dependency-installs` | -                                                                         | Async. Reset all dependency installs |
+
+## Nexus Mods integration
+
+| Event                    | Args                                                                      | Description                          |
+| ------------------------ | ------------------------------------------------------------------------- | ------------------------------------ |
+| `nexus-download`         | `(siteId, modId, fileId, ...)`                                            | Async. Download mod from Nexus       |
+| `endorse-nexus-mod`      | `(siteId: string, modId: string, version: string, endorseStatus: string)` | Async. Endorse a mod                 |
+| `check-mods-version`     | `(gameId, modIds?, ...)`                                                  | Async. Check mods for updates        |
+| `get-mod-files`          | `(siteId, modId, ...)`                                                    | Async. Get available files for a mod |
+| `get-latest-mods`        | -                                                                         | Async. Get latest mods               |
+| `get-trending-mods`      | -                                                                         | Async. Get trending mods             |
+| `refresh-user-info`      | -                                                                         | Refresh Nexus user info / session    |
+| `request-nexus-login`    | `(cb)`                                                                    | Prompt user to log in to Nexus       |
+| `did-login`              | `(err: Error)`                                                            | Nexus login completed                |
+| `retrieve-category-list` | `(isUpdate: boolean)`                                                     | Fetch category list from Nexus       |
+| `update-categories`      | `(gameId, categories, isUpdate)`                                          | Update mod categories                |
+| `open-mod-page`          | -                                                                         | Open mod page on Nexus               |
+| `mod-update`             | -                                                                         | A mod has an update available        |
+| `mods-update`            | -                                                                         | Multiple mods have updates           |
+| `submit-feedback`        | -                                                                         | Submit user feedback                 |
+| `send-metric`            | -                                                                         | Async. Send metric to Nexus          |
+
+## Collections
+
+| Event                             | Args                               | Description                         |
+| --------------------------------- | ---------------------------------- | ----------------------------------- |
+| `get-nexus-collection`            | `(collectionId, revisionId?, ...)` | Async. Get a Nexus collection       |
+| `get-nexus-collections`           | -                                  | Async. Get multiple collections     |
+| `get-my-collections`              | -                                  | Async. Get user's collections       |
+| `get-nexus-collection-revision`   | -                                  | Async. Get collection revision      |
+| `resolve-collection-url`          | `(collectionUrl: string)`          | Async. Resolve URL to collection ID |
+| `rate-nexus-collection-revision`  | -                                  | Async. Rate a collection revision   |
+| `will-install-collection`         | -                                  | Async. Before collection install    |
+| `did-install-collection`          | -                                  | Collection was installed            |
+| `did-download-collection`         | -                                  | Collection was downloaded           |
+| `collection-postprocess-complete` | -                                  | Collection post-processing done     |
+| `collection-mod-skipped`          | -                                  | A mod in the collection was skipped |
+| `submit-collection`               | -                                  | Submit collection to Nexus          |
+| `update-conflicts-and-rules`      | -                                  | Async. Update collection conflicts  |
+
+## Extensions
+
+| Event                             | Args                            | Description                              |
+| --------------------------------- | ------------------------------- | ---------------------------------------- |
+| `install-extension`               | `(ext: IExtensionDownloadInfo)` | Async. Install an extension              |
+| `install-extension-from-download` | `(archiveId: string)`           | Async. Install extension from download   |
+| `show-extension-page`             | `(modId: number)`               | Show extension manager page              |
+| `download-script-extender`        | `(gameId: string)`              | Async. Download script extender for game |
+
+## Settings
+
+| Event              | Args                                                          | Description                         |
+| ------------------ | ------------------------------------------------------------- | ----------------------------------- |
+| `bake-settings`    | `(gameId: string, mods: IMod[], profile: IProfile)`           | Async. Apply settings to game files |
+| `apply-settings`   | `(profile: IProfile, filePath: string, parser: IniFile<any>)` | Async. Apply INI/config settings    |
+| `settings-changed` | `(path: string[])`                                            | Application settings changed        |
+
+## UI & navigation
+
+| Event                 | Args                                                              | Description                   |
+| --------------------- | ----------------------------------------------------------------- | ----------------------------- |
+| `show-main-page`      | `(pageId: string)`                                                | Navigate to a main page       |
+| `refresh-main-page`   | -                                                                 | Refresh current main page     |
+| `open-knowledge-base` | `(articleId: string)`                                             | Open a knowledge base article |
+| `hide-modal`          | `(modal: string)`                                                 | Hide a modal dialog           |
+| `preview-files`       | `(files: IPreviewFile[], cb?: (selection: IPreviewFile) => void)` | Show file preview dialog      |
+| `quick-launch`        | -                                                                 | Quick launch game/tool        |
+
+## Analytics
+
+| Event                         | Args                                                                 | Description           |
+| ----------------------------- | -------------------------------------------------------------------- | --------------------- |
+| `analytics-track-event`       | `(category: string, action: string, label?: string, value?: number)` | Track analytics event |
+| `analytics-track-click-event` | `(page: string, element: string)`                                    | Track UI click        |
+
+## Miscellaneous
+
+| Event              | Args                                  | Description                  |
+| ------------------ | ------------------------------------- | ---------------------------- |
+| `startup`          | -                                     | Application startup complete |
+| `report-feedback`  | `(errorMessage: string)`              | Report feedback/error        |
+| `trigger-test-run` | `(eventType: string, delay?: number)` | Trigger test runner          |

package/docs/EXAMPLES.md

@@ -0,0 +1,75 @@
+# Example Extensions
+
+These open-source extensions are good references for advanced patterns.
+
+### Built-in (bundled with Vortex)
+
+- [`game-witcher3`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-witcher3) - 6 installers, script merger auto-download, XML merge support, collections, load order, custom reducers
+- [`game-nomanssky`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-nomanssky) - mod type migration system that converts mods between deprecated and current formats
+- [`game-morrowind`](https://github.com/Nexus-Mods/Vortex/tree/master/extensions/games/game-morrowind) - load order with validation, collections support, multi-language/locale handling
+
+### Community
+
+#### [Cyberpunk 2077](https://github.com/E1337Kat/cyberpunk2077_ext_redux)
+
+A large-scale extension supporting 14+ mod frameworks (REDmod, Red4Ext, CET, Redscript, TweakXL, etc.). Notable patterns:
+
+- **Multi-type installer** - a single archive can contain multiple mod types; the extension detects and sequences them automatically ([installer.multitype.ts](https://github.com/E1337Kat/cyberpunk2077_ext_redux/blob/5a069f0/src/installer.multitype.ts))
+- **Layout-based detection** - infers mod type from file structure rather than metadata, with legacy format auto-conversion ([installers.layouts.ts](https://github.com/E1337Kat/cyberpunk2077_ext_redux/blob/5a069f0/src/installers.layouts.ts))
+- **Tool hooks** - intercepts tool execution to trigger REDmod deployment before launch ([tools.redmodding.ts](https://github.com/E1337Kat/cyberpunk2077_ext_redux/blob/5a069f0/src/tools.redmodding.ts))
+- **Dynamic feature flags** - user-configurable features backed by Redux store ([features.ts](https://github.com/E1337Kat/cyberpunk2077_ext_redux/blob/5a069f0/src/features.ts))
+- **Load order with REDmod deployment** - ties load order serialization to the REDmod compilation pipeline ([load_order.ts](https://github.com/E1337Kat/cyberpunk2077_ext_redux/blob/5a069f0/src/load_order.ts))
+- **Game store DLC prompts** - detects Steam/GOG/Epic and prompts users to install REDmod DLC via store-specific protocol handlers ([redmodding.ts](https://github.com/E1337Kat/cyberpunk2077_ext_redux/blob/5a069f0/src/redmodding.ts))
+
+#### [Mount & Blade II: Bannerlord](https://github.com/BUTR/game-mount-and-blade2)
+
+A feature-rich extension with native module integration and save game management. Notable patterns:
+
+- **Load order with auto-sort** - advanced load order management with auto-sort on deploy, bulk enable/disable, and per-profile persistence ([loadOrder/](https://github.com/BUTR/game-mount-and-blade2/tree/c04fced/src/loadOrder))
+- **Save game viewer** - custom UI for browsing and loading save files with BLSE support ([views/](https://github.com/BUTR/game-mount-and-blade2/tree/c04fced/src/views))
+- **Collections support** - full integration with Vortex collections including addung custom data such as load order and mod options ([collections/](https://github.com/BUTR/game-mount-and-blade2/tree/c04fced/src/collections))
+- **Custom settings UI** - registers a game specific settings panels with sort-on-deploy, auto-fix toggles ([settings/](https://github.com/BUTR/game-mount-and-blade2/tree/c04fced/src/settings))
+
+#### [Ready Or Not](https://github.com/BeYkeRYkt/vortex_readyornot_extension)
+
+Handles 6 specialized mod types (FMOD audio, movies, configs, saves, binaries, root). Notable patterns:
+
+- **Prefix-based load ordering** - uses alphabetic prefixes (`AAA_`, `AAB_`, ...) so filesystem sorting matches user-defined priority ([index.js](https://github.com/BeYkeRYkt/vortex_readyornot_extension/blob/9448452/index.js))
+- **Type-specific installer pairs** - each mod type has paired `test*()` and `install*()` functions for validation and routing
+- **Corrupt load order recovery** - gracefully handles corrupted `loadOrder.json` with auto-rebuild
+
+#### [Valheim](https://github.com/sqrrlmstr/Valheim-Extension)
+
+Manages BepInEx framework deployment and Thunderstore integration. Notable patterns:
+
+- **Thunderstore API integration** - fetches and downloads BepInEx packs directly from the Thunderstore API with error handling and rate limiting ([index.js](https://github.com/sqrrlmstr/Valheim-Extension/blob/e52a287/index.js))
+- **Per-mod directory isolation** - segregates each mod into `BepInEx/plugins/[ModName]/` to prevent naming conflicts
+- **Timestamp-based conflict resolution** - compares file modification times to prevent unintended overwrites
+
+#### [Elden Ring](https://github.com/Senjay-id/eldenring-vortex-extension)
+
+Supports ModEngine 2 and seamless co-op mods. Notable patterns:
+
+- **Framework auto-download** - `prepareForModding` downloads required mod framework dependencies during initial setup ([src/index.ts](https://github.com/Senjay-id/eldenring-vortex-extension/blob/47631fc/src/index.ts))
+- **Auto-set primary tool** - `onDidDeploy` hook automatically sets ModEngine 2 as the primary tool when mods are deployed
+- **Multi-installer routing** - 5 priority-based installers route mods to the correct handler based on type (co-op, mod loaders, DLLs, full ModEngine 2 mods)
+
+### Nexus-maintained
+
+#### [Starfield](https://github.com/Nexus-Mods/game-starfield)
+
+Supports Steam and Xbox Game Pass with platform-aware deployment. Notable patterns:
+
+- **Directory junction strategy** - creates junctions between the game's Data folder and Documents path for unified mod deployment across platforms ([setup.ts](https://github.com/Nexus-Mods/game-starfield/blob/30ea5cb/src/setup.ts))
+- **INI merge system** - merges ASI mod configurations into a unified INI file during deployment ([iniMerge.ts](https://github.com/Nexus-Mods/game-starfield/blob/30ea5cb/src/merges/iniMerge.ts))
+- **Conditional LOOT integration** - load order with LOOT auto-sort when available, fallback to manual drag-and-drop ([StarFieldLoadOrder.tsx](https://github.com/Nexus-Mods/game-starfield/blob/30ea5cb/src/loadOrder/StarFieldLoadOrder.tsx))
+- **Platform-specific installers** - separate installers for SFSE (Steam) and ASI loader (Xbox) ([installers/](https://github.com/Nexus-Mods/game-starfield/tree/30ea5cb/src/installers))
+
+#### [Oblivion Remastered](https://github.com/Nexus-Mods/game-oblivionremastered)
+
+Manages 6 mod formats for a UE5-based Gamebryo remaster. Notable patterns:
+
+- **UE4SS auto-download** - automatically downloads and configures UE4SS framework from GitHub releases with version checking ([downloader.ts](https://github.com/Nexus-Mods/game-oblivionremastered/blob/489f6b9/src/downloader.ts))
+- **Stop pattern validation** - regex-based file hierarchy validation to prevent invalid mod structures ([stopPatterns.ts](https://github.com/Nexus-Mods/game-oblivionremastered/blob/489f6b9/src/stopPatterns.ts))
+- **Architecture-aware binaries** - handles Win64 vs WinGDK paths for Steam and Xbox builds ([modTypes.ts](https://github.com/Nexus-Mods/game-oblivionremastered/blob/489f6b9/src/modTypes.ts))
+- **Deployment event pipeline** - INI merging on `will-deploy`, Lua mod processing on `did-deploy`, settings bake on load order change ([eventHandlers.ts](https://github.com/Nexus-Mods/game-oblivionremastered/blob/489f6b9/src/eventHandlers.ts))