Difference between revisions of "Vortex API Events"

From Nexus Mods Wiki
Jump to: navigation, search
m (Commands)
m (Commands)
Line 329: Line 329:
 
== Commands ==
 
== Commands ==
 
=== Start Download URL ===
 
=== Start Download URL ===
Intruct Vortex to download the file at a given URL and name the resulting file.
+
Instruct Vortex to download the file at a given URL and name the resulting file.
 
{| class="wikitable" style="width:80%"
 
{| class="wikitable" style="width:80%"
 
| style="width:10%" | Name
 
| style="width:10%" | Name
Line 344: Line 344:
 
|}
 
|}
 
=== Show Balloon ===
 
=== Show Balloon ===
Intruct Vortex to display a notification to the user.
+
Instruct Vortex to display a notification to the user.
 
{| class="wikitable" style="width:80%"
 
{| class="wikitable" style="width:80%"
 
| style="width:10%" | Name
 
| style="width:10%" | Name
Line 359: Line 359:
 
|}
 
|}
 
=== Deploy Mods ===
 
=== Deploy Mods ===
Intruct Vortex to .
+
Instruct Vortex to deploy all mods for the active profile. This is an asynchronous function.  
 
{| class="wikitable" style="width:80%"
 
{| class="wikitable" style="width:80%"
 
| style="width:10%" | Name
 
| style="width:10%" | Name
Line 365: Line 365:
 
|-
 
|-
 
| Parameters
 
| Parameters
|<code></code>
+
|<code>(callback: (err: Error) => void, profileId?: string, progressCB?: (text: string, percent: number) => void)</code>
 
|-
 
|-
 
| Example
 
| Example
 
|<pre>
 
|<pre>
context.api.events.emit('', );
+
context.api.events.emit('deploy-mods', (err) => console.warn(`Error deploying mods \n${err}` );
 
</pre>
 
</pre>
 
|-
 
|-
 
|}
 
|}
 
=== Deploy Single Mod ===
 
=== Deploy Single Mod ===
Intruct Vortex to .
+
Instruct Vortex to asynchronously deploy all files from a single mod, ignoring file conflicts. This command should only be used in very specific cases.
 
{| class="wikitable" style="width:80%"
 
{| class="wikitable" style="width:80%"
 
| style="width:10%" | Name
 
| style="width:10%" | Name
Line 380: Line 380:
 
|-
 
|-
 
| Parameters
 
| Parameters
|<code></code>
+
|<code>(gameId: string, modId: string, enable?: boolean)</code>
 
|-
 
|-
 
| Example
 
| Example
 
|<pre>
 
|<pre>
context.api.events.emit('', );
+
context.api.emitAndAwait('deploy-single-mod', gameId, modId, enable);
 
</pre>
 
</pre>
 
|-
 
|-
 
|}
 
|}
 
=== Purge Mods In Path ===
 
=== Purge Mods In Path ===
Intruct Vortex to .
+
Instruct Vortex to asynchronously purge a specific mod type, overriding the deployment target. This is intended to be used to clean up when an upgrade to a game extension changed the way mods get deployed such that the deployment target the new version would dynamically generate doesn't match where the old version deployed to.
 
{| class="wikitable" style="width:80%"
 
{| class="wikitable" style="width:80%"
 
| style="width:10%" | Name
 
| style="width:10%" | Name
Line 395: Line 395:
 
|-
 
|-
 
| Parameters
 
| Parameters
|<code></code>
+
|<code>(gameId: string, modType: string, modPath: string)</code>
 
|-
 
|-
 
| Example
 
| Example
 
|<pre>
 
|<pre>
context.api.events.emit('', );
+
context.api.emitAndAwait('purge-mods-in-path', gameId, modType, modPath);
 
</pre>
 
</pre>
 
|-
 
|-
 
|}
 
|}
 
=== Purge Mods ===
 
=== Purge Mods ===
Intruct Vortex to .
+
Intruct Vortex to purge the currently deployed mods.
 
{| class="wikitable" style="width:80%"
 
{| class="wikitable" style="width:80%"
 
| style="width:10%" | Name
 
| style="width:10%" | Name
Line 410: Line 410:
 
|-
 
|-
 
| Parameters
 
| Parameters
|<code></code>
+
|<code>(allowFallback: boolean, callback: (err: Error) => void)</code>
 
|-
 
|-
 
| Example
 
| Example
 
|<pre>
 
|<pre>
context.api.events.emit('', );
+
context.api.events.emit('purge-mods', allowFallback, (err) => console.warn(`Purge mods error \n ${err}`));
 
</pre>
 
</pre>
 
|-
 
|-
 
|}
 
|}
 
=== Start Install ===
 
=== Start Install ===
Intruct Vortex to .
+
Intruct Vortex to start installing an archive as a mod.
 
{| class="wikitable" style="width:80%"
 
{| class="wikitable" style="width:80%"
 
| style="width:10%" | Name
 
| style="width:10%" | Name
Line 425: Line 425:
 
|-
 
|-
 
| Parameters
 
| Parameters
|<code></code>
+
|<code>(archivePath: string, callback: (err: Error, modId: string) => void)</code>
 
|-
 
|-
 
| Example
 
| Example
 
|<pre>
 
|<pre>
context.api.events.emit('', );
+
context.api.events.emit('start-install', archivePath,
 +
    (err, modId) => console.log(`Created Mod ${modId} from archive at ${archivePath}`)
 +
);
 
</pre>
 
</pre>
 
|-
 
|-
 
|}
 
|}
 
=== Start Install Download ===
 
=== Start Install Download ===
Intruct Vortex to .
+
Intruct Vortex to start installing a file that has been downloaded through Vortex.
 
{| class="wikitable" style="width:80%"
 
{| class="wikitable" style="width:80%"
 
| style="width:10%" | Name
 
| style="width:10%" | Name
Line 440: Line 442:
 
|-
 
|-
 
| Parameters
 
| Parameters
|<code></code>
+
|<code>(downloadId: string, allowAutoEnable: boolean, callback: (err: Error, modId: string) => void, forceInstaller: string)</code>
 
|-
 
|-
 
| Example
 
| Example
 
|<pre>
 
|<pre>
context.api.events.emit('', );
+
context.api.events.emit('start-install-download', downloadId, allowAutoEnable,
 +
    (err, modId) => console.log(`Created Mod ${modId} from download Id ${downloadId}`)
 +
);
 
</pre>
 
</pre>
 
|-
 
|-
 
|}
 
|}
 
=== Remove Mod ===
 
=== Remove Mod ===
Intruct Vortex to .
+
Intruct Vortex to delete a mod. This is not reversible.  
 
{| class="wikitable" style="width:80%"
 
{| class="wikitable" style="width:80%"
 
| style="width:10%" | Name
 
| style="width:10%" | Name
Line 455: Line 459:
 
|-
 
|-
 
| Parameters
 
| Parameters
|<code></code>
+
|<code>(gameMode: string, modId: string, callback: (err: Error) => void)</code>
 
|-
 
|-
 
| Example
 
| Example
 
|<pre>
 
|<pre>
context.api.events.emit('', );
+
context.api.events.emit('remove-mod', gameMode, modId, (err) => console.log(`Mod deleted $(modId)`));
 
</pre>
 
</pre>
 
|-
 
|-
 
|}
 
|}
 
=== Create Mod ===
 
=== Create Mod ===
Intruct Vortex to .
+
Intruct Vortex to create a new, empty mod.
 
{| class="wikitable" style="width:80%"
 
{| class="wikitable" style="width:80%"
 
| style="width:10%" | Name
 
| style="width:10%" | Name
Line 470: Line 474:
 
|-
 
|-
 
| Parameters
 
| Parameters
|<code></code>
+
|<code>(gameMode: string, mod: IMod, callback: (err: Error) => void)</code>
 
|-
 
|-
 
| Example
 
| Example
 
|<pre>
 
|<pre>
context.api.events.emit('', );
+
context.api.events.emit('create-mod', gameMode, mod, (err) => console.log('Created a new mod');
 
</pre>
 
</pre>
 
|-
 
|-
 
|}
 
|}
 
=== Update Categories ===
 
=== Update Categories ===
Intruct Vortex to .
+
Intruct Vortex to make changes to the categories for a game, optionally completely overwriting them.
 
{| class="wikitable" style="width:80%"
 
{| class="wikitable" style="width:80%"
 
| style="width:10%" | Name
 
| style="width:10%" | Name
Line 485: Line 489:
 
|-
 
|-
 
| Parameters
 
| Parameters
|<code></code>
+
|<code>(gameId: string, categories: { [id: string]: ICategory }, isUpdate: boolean)</code>
 
|-
 
|-
 
| Example
 
| Example
 
|<pre>
 
|<pre>
context.api.events.emit('', );
+
context.api.events.emit('update-categories', (gameId, categories, isUpdate) => console.log(`Categories updated for ${gameId}`));
 
</pre>
 
</pre>
 
|-
 
|-
 
|}
 
|}
 
=== Activate Game ===
 
=== Activate Game ===
Intruct Vortex to .
+
Intruct Vortex to switch the currently managed game.
 
{| class="wikitable" style="width:80%"
 
{| class="wikitable" style="width:80%"
 
| style="width:10%" | Name
 
| style="width:10%" | Name
Line 500: Line 504:
 
|-
 
|-
 
| Parameters
 
| Parameters
|<code></code>
+
|<code>(gameId: string)</code>
 
|-
 
|-
 
| Example
 
| Example
 
|<pre>
 
|<pre>
context.api.events.emit('', );
+
context.api.events.emit('activate-game', (gameId) => console.log(`Vortex will switch to manage ${gameId}`));
 
</pre>
 
</pre>
 
|-
 
|-

Revision as of 10:15, 17 June 2020

VortexLogoSmall.png This content applies to Vortex 1.2.16.

This page will document all the events Vortex can send and receive using the Vortex API.

Interacting with events

You can both catch and emit all events inside Vortex. The Vortex API is accessed as a property of the context object.

In order to have your extension respond to an event you can use the following:

context.api.events.on('eventName', callback);

context.api.onAsync('eventName', callback);

To emit an event (or command) yourself use the following:

context.api.events.emit('eventName', callback);

context.api.emitAndAwait('eventName', callback);

Notice that the asynchronous version is called from the API object directly, rather than from the events property.

Events

Mods Enabled

Emitted by Vortex when one or more mods are enabled.

Name mods-enabled
Parameters (mods: string[], enabled: boolean, gameId: string)
Example
context.api.events.on('mods-enabled', 
    (mods, enabled, gameId) => console.log(`${mods.count} mods ${enabled ? 'enabled' : 'disabled'} in ${gameId}`) 
);

Game Mode Activated

Emitted by Vortex when switching the currently managed game, including when the application first starts.

Name gamemode-activated
Parameters (gameId: string)
Example
context.api.events.on('gamemode-activated', 
    (gameId) => console.log(`Activated game mode in ${gameId}`) 
);
Notes
  • The gameId property can be undefined. This usually happens when the user deletes their last profile for an active game.

Startup

Emitted by Vortex when the application first starts (after the extensions are loaded by before the UI is displayed).

Name startup
Parameters none
Example
context.api.events.on('startup', 
    () => console.log('Vortex is starting up.') 
);

Will Deploy

Emitted asynchronously by Vortex before starting a deployment.

Name will-deploy
Parameters (profileId: string, oldDeployment: { [modType: string]: IDeployedFile[] })
Example
context.api.onAsync('will-deploy', 
    (profiled, oldDeployment) => console.log(`About to deploy mods for profile ${profileId}`) 
);

context.api.emitAndAwait('will-deploy', profileId, lastDeployment);

Did Deploy

Emitted asynchronously by Vortex after finishing a deployment.

Name did-deploy
Parameters (profileId: string, newDeployment: { [modType: string]: IDeployedFile[] })
Example
context.api.onAsync('did-deploy', 
    (profiled, newDeployment) => console.log(`Finished deploying mods for profile ${profileId}`) 
);

context.api.emitAndAwait('did-deploy', profileId, thisDeployment);

Profile Will Change

Emitted by Vortex before switching between profiles.

Name profile-will-change
Parameters (newProfileId: string, enqueue: (cb: () => Promise<void>) => void)
Example
context.api.events.on('profile-will-change', 
    (newProfileId, enqueue: () => undefined) => console.log(`Preparing to switch to profile ${newProfileId}`) 
);
Notes
  • The events profile-will-change and profile-did-change also fire when swapping between games, because each game has a separate profile.
  • The newProfileId property can be undefined if the user deletes the last profile for their active game.
  • The enqueue function can be used to return a Promise which needs to be fulfilled before the profile may be changed. The change can not be cancelled though because we can't know if/how previous changes can be rolled back.

Profile Did Change

Emitted by Vortex after switching between profiles.

Name profile-did-change
Parameters (newProfileId: string)
Example
context.api.events.on('profile-did-change', 
    (newProfileId => console.log(`Finished switching to profile ${newProfileId}`) 
);
Notes
  • The events profile-will-change and profile-did-change also fire when swapping between games, because each game has a separate profile.
  • The newProfileId property can be undefined if the user deletes the last profile for their active game.

Did Import Downloads

Emitted by Vortex after adding new downloads to the downloads section.

Name did-import-downloads
Parameters (dlIds: string[])
Example
context.api.events.on('did-import-downloads', 
    (dlIds => console.log(`Imported ${dlIds.length} downloads`) 
);

Will Move Downloads

Emitted by Vortex before the user relocates their download folder for a game.

Name will-move-downloads
Parameters none
Example
context.api.events.on('profile-did-change', 
    (() => console.log('Vortex is preparing to move downloads.') 
);

Filehash Calculated

Emitted by Vortex after the user adds a new file and its MD5 has been calculated.

Name filehash-calculated
Parameters (filePath: string, fileMD5: string, fileSize: number)
Example
context.api.events.on('filehash-calculated', 
    (filePath, fileMD5, fileSize) => console.log(`File at ${filePath} is ${fileSize} bytes with MD5 of ${fileMD5}`) 
);

Added Files

Emitted asynchronously by Vortex if new files have been created in the mods folder and Vortex has attempted to identify where they came from.

Name added-files
Parameters (profileId: string, newFiles: Array<{ filePath: string, candidates: string[] }>)
Example
context.api.onAsync('added-files', 
    (profileId, newFiles) => {
        const fileInfo = newFiles.map(f => `File${f.filePath} could be a part of the following mods ${f.candidates.join('\n')}`).join('\n');
        console.log(`New files detected in the mods folder for ${profileId}\n${fileInfo}`);
    }) 
);

Mod Enabled

Emitted by Vortex when a mod is toggled from disabled to enabled.

Name mod-enabled
Parameters (profileId: string, modId: string)
Example
context.api.events.on('mod-enabled', (profileId, modId) => console.log(`Mod ${modId} enabled in ${profileId}`) 
);

Mod Disabled

Emitted by Vortex when a mod is toggled from enabled to disabled.

Name mod-disabled
Parameters (profileId: string, modId: string)
Example
context.api.events.on('mod-disabled', (profileId, modId) => console.log(`Mod ${modId} disabled in ${profileId}`) 
);

Mod Content Changed

Emitted when Vortex determines the files inside a mod were changed (files might have been deleted or added). Primarily useful to update caches.

Name mod-content-changed
Parameters (profileId: string, modId: string)
Example
context.api.events.on('mod-content-changed', (profileId, modId) => console.log(`Mod ${modId} in ${profileId} changed`) 
);

Will Purge

Emitted by Vortex before purging deployed mods.

Name will-purge
Parameters (profileId: string, deployment: IDeployment)
Example
context.api.events.on('will-purge', (profileId, deployment) => console.log(`Preparing to purge on profile ${profileId}`) 
);

Did Purge

Emitted by Vortex after purging deployed mods.

Name did-purge
Parameters (profileId: string)
Example
context.api.events.on('did-purge', (profileId) => console.log(`Finished purge on profile ${profileId}`) 
);

Commands

Start Download URL

Instruct Vortex to download the file at a given URL and name the resulting file.

Name start-download-url
Parameters (url: string, fileName: string)
Example
context.api.events.emit('start-download-url', url, fileName);

Show Balloon

Instruct Vortex to display a notification to the user.

Name show-balloon
Parameters (title: string, content: string)
Example
context.api.events.emit('show-balloon', title, content);

Deploy Mods

Instruct Vortex to deploy all mods for the active profile. This is an asynchronous function.

Name deploy-mods
Parameters (callback: (err: Error) => void, profileId?: string, progressCB?: (text: string, percent: number) => void)
Example
context.api.events.emit('deploy-mods', (err) => console.warn(`Error deploying mods \n${err}` );

Deploy Single Mod

Instruct Vortex to asynchronously deploy all files from a single mod, ignoring file conflicts. This command should only be used in very specific cases.

Name deploy-single-mod
Parameters (gameId: string, modId: string, enable?: boolean)
Example
context.api.emitAndAwait('deploy-single-mod', gameId, modId, enable);

Purge Mods In Path

Instruct Vortex to asynchronously purge a specific mod type, overriding the deployment target. This is intended to be used to clean up when an upgrade to a game extension changed the way mods get deployed such that the deployment target the new version would dynamically generate doesn't match where the old version deployed to.

Name purge-mods-in-path
Parameters (gameId: string, modType: string, modPath: string)
Example
context.api.emitAndAwait('purge-mods-in-path', gameId, modType, modPath);

Purge Mods

Intruct Vortex to purge the currently deployed mods.

Name purge-mods
Parameters (allowFallback: boolean, callback: (err: Error) => void)
Example
context.api.events.emit('purge-mods', allowFallback, (err) => console.warn(`Purge mods error \n ${err}`));

Start Install

Intruct Vortex to start installing an archive as a mod.

Name start-install
Parameters (archivePath: string, callback: (err: Error, modId: string) => void)
Example
context.api.events.emit('start-install', archivePath,
    (err, modId) => console.log(`Created Mod ${modId} from archive at ${archivePath}`) 
);

Start Install Download

Intruct Vortex to start installing a file that has been downloaded through Vortex.

Name start-install-download
Parameters (downloadId: string, allowAutoEnable: boolean, callback: (err: Error, modId: string) => void, forceInstaller: string)
Example
context.api.events.emit('start-install-download', downloadId, allowAutoEnable,
    (err, modId) => console.log(`Created Mod ${modId} from download Id ${downloadId}`)
);

Remove Mod

Intruct Vortex to delete a mod. This is not reversible.

Name remove-mod
Parameters (gameMode: string, modId: string, callback: (err: Error) => void)
Example
context.api.events.emit('remove-mod', gameMode, modId, (err) => console.log(`Mod deleted $(modId)`));

Create Mod

Intruct Vortex to create a new, empty mod.

Name create-mod
Parameters (gameMode: string, mod: IMod, callback: (err: Error) => void)
Example
context.api.events.emit('create-mod', gameMode, mod, (err) => console.log('Created a new mod');

Update Categories

Intruct Vortex to make changes to the categories for a game, optionally completely overwriting them.

Name update-categories
Parameters (gameId: string, categories: { [id: string]: ICategory }, isUpdate: boolean)
Example
context.api.events.emit('update-categories', (gameId, categories, isUpdate) => console.log(`Categories updated for ${gameId}`));

Activate Game

Intruct Vortex to switch the currently managed game.

Name activate-game
Parameters (gameId: string)
Example
context.api.events.emit('activate-game', (gameId) => console.log(`Vortex will switch to manage ${gameId}`));

Internal Events