LEGACY Other API Events

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

One way an extension integrates with Vortex is by reacting to global events triggered by the main application. That way your extension can become part of the regular workflow in the application, e.g. doing work every time Vortex deploys mod.

Contributing

The event lists below are generated from this data file: https://github.com/Nexus-Mods/vortex-api/blob/master/docs/_data/events.yml

If you want to improve the documentation, please fork this repo and make a pull request with your improvements.

Interacting with events

There are two different ways we trigger events:

• “fire-and-forget” where the emitter emits an event and immediately continues its own work.
• “async” where the emitter waits for all event handlers to complete successfully

If it’s unclear from context, please consult the event list to figure out which kind an event is because you need to use the appropriate emit/on function based on the event type. Further we divide the list into “events” and “commands”, with “events” being events that the Vortex core triggers and the extension is expected to catch to react to them and “commands” being events that extensions are supposed to trigger and Vortex core or another extension reacts to.

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

context.api.events.on('eventName', callback); // fire-and-forget

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

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

context.api.events.emit('eventName', callback); // fire-and-forget

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

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)
Notes	The gameId property can be undefined. This usually happens when the user deletes their last profile for an active game.
Example

context.api.events.on('gamemode-activated', 
    (gameId) => console.log(`Activated game mode in ${gameId}`) 
);

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', 
    (profileId, 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)
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.

Example

context.api.events.on('profile-will-change', 
    (newProfileId, enqueue: () => undefined) => console.log(`Preparing to switch to profile ${newProfileId}`) 
);

Profile Did Change

Emitted by Vortex after switching between profiles.

Name	profile-did-change
Parameters	(newProfileId: string)
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.

Example

context.api.events.on('profile-did-change', 
    (newProfileId => console.log(`Finished switching to profile ${newProfileId}`) 
);

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. Instruct Vortex to display a notification to the user.

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

Instruct Vortex to purge the currently deployed mods.

Name	purge-mods
Parameters	(allowFallback: boolean, callback: (err: Error) => void)

Example

context.api.events.emit('purge-mods', true, (err) => console.warn(`Purge mods error \n ${err}`));

Start Install

Instruct 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

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

Name	start-install
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

Instruct 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

Instruct 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

Instruct 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);

Activate Game

Instruct Vortex to switch the currently managed game.

Name	activate-game
Parameters	(gameId: string)

Example

context.api.events.emit('activate-game', gameId);

Check Mods Version

Instruct Vortex to check for updates on the specified mods.

Name	check-mods-version
Parameters	(gameId: string, mods: { [id: string]: IMod }, forceFull: boolean)
Notes	If forceFull is false (or undefined) Vortex may use cached data for this update check. This is to prevent using more requests than necessary.

Example

context.api.events.emit('check-mods-version', gameId, mods, forceFull);

Nexus Download

Instruct Vortex to asynchronously download a file from Nexus Mods.

Name	nexus-download
Parameters	(gameId: string, modId: string, fileId: string)

Example

context.api.emitAndAwait('nexus-download', gameId, modId, fileId);

Endorse Nexus Mod

Instruct Vortex to asynchronously send an endorsement to Nexus Mods.

Name	endorse-nexus-mod
Parameters	(gameId: string, nexusModId: number, version: string, endorsedStatus: EndorsedStatus)

Example

context.api.emitAndAwait('endorse-nexus-mod', gameId, nexusModId, version, endorsedStatus);

Endorse Mod

Instruct Vortex to toggle the endorsement status of a mod locally.

Name	endorse-mod
Parameters	(gameId: string, modId: string, endorsedStatus: EndorsedStatus)

Example

context.api.events.emit('endorse-mod', gameId, modId, endorsedStatus);

Submit Feedback

Instruct Vortex to toggle the send feedback to the Nexus Mods team. It is unlikely this will need to be used by a user extension.

Name	submit-feedback
Parameters	(title: string, message: string, hash: string, feedbackFiles: string[], anonymous: boolean, callback: (err: Error, response?: IFeedbackResponse) => void)

Example

context.api.events.emit('submit-feedback', title, message, hash, feedbackFiles, anonymous, 
    (err, response) => console.log('Feedback response', response)
);

Mod Update

Instruct Vortex to update a mod which is showing an update pending.

Name	mod-update
Parameters	(gameId: string, modId: string, fileId: string)

Example

context.api.events.emit('mod-update', gameId, modId, fileId);

Open Mod Page

Instruct Vortex to update the listed download page for the selected mod.

Name	open-mod-page
Parameters	(gameId: string, modId: string, source: string)
Notes	If the mod is not from Nexus Mods, your extension will need to handle these events.

Example

context.api.events.emit('open-mod-page', gameId, modId, source);

Enable Download Watch

Instruct Vortex to start or stop watching the downloads folder for newly added files.

Name	enable-download-watch
Parameters	(enabled: boolean)
Notes	When importing mods, if you intend to create database entries for the archives yourself, it may make sense to disable this but make sure to re-enable afterwards and to have a modal dialog to prevent the user from manually adding files while this is disabled.

Example

context.api.events.emit('enable-download-watch', enabled);

Autosort Plugins

Intruct Vortex to run the autosort operation for an active Gamebyro game.

Name	autosort-plugins
Parameters	(manual: boolean, callback: (err: Error) => void)

Example

context.api.events.emit('autosort-plugins', manual, (err) => console.log('Autosorting'));

Show Main Page

Intruct Vortex to display the specified page of the app (e.g. Mods, Downloads, Settings).

Name	show-main-page
Parameters	(pageId: string)
Notes	To show a custom page you'll first need to register it.

Example

context.api.events.emit('show-main-page', pageId);

Show Modal

Intruct Vortex to display the specified modal box.

Name	show-modal
Parameters	(id: string)
Notes	To show a custom modal you'll first need to register it.

Example

context.api.events.emit('show-modal', id);

Import Downloads

Intruct Vortex to copy the listed files into your active downloads directory.

Name	import-downloads
Parameters	(downloadPaths: string[])

Example

context.api.events.emit('import-downloads', downloadPaths);

Remove Download

Intruct Vortex to delete a download from your active downloads directory.

Name	remove-download
Parameters	(downloadId: string)

Example

context.api.events.emit('remove-download', downloadId);

Pause Download

Intruct Vortex to pause an active download.

Name	pause-download
Parameters	(downloadId: string)

Example

context.api.events.emit('pause-download', downloadId);

Resume Download

Instruct Vortex to resume a paused download.

Name	resume-download
Parameters	(downloadId: string, callback: (err: Error, id: string) => void)

Example

context.api.events.emit('resume-download', downloaded (err, id) => console.log(`Resumed download ${id}`));

Start Download

Instruct Vortex to start a download from the internet to your active downloads directory.

Name	start-download
Parameters	(urls: string[], modInfo: any, fileName: string, callback: (err: Error, id: string) => void, redownload: RedownloadMode)
Note	Multiple URLs can be specified to download from multiple sources or to have a fallback if one doesn't work, however this currently has no effect.

Example

context.api.events.emit('start-download', urls, modInfo, fileName, 
    (err, id) => console.log('Starting download', id), redownload
);

Quick Launch

Instruct Vortex to run the primary executable/tool for the active game.

Name	quick-launch
Parameters	none

Example

context.api.events.emit('quick-launch');

Trigger Test Run

Instruct Vortex to start run validity checks that find problems with the setup of Vortex or the game.

Name	trigger-test-run
Parameters	(eventType: string, delay: number)
Notes	If you would like to include your own tests, you will first need to register them.

Example

context.api.events.emit('trigger-test-run', eventType, delay);

Install Extension

Instruct Vortex to asynchronously install an extension.

Name	install-extension
Parameters	(extensionInfo: IExtensionDownloadInfo)

Example

context.api.emitAndWait('install-extension', extensionInfo);

Browse For Download

Intruct Vortex to open the built-in web browser to a specified page, then exit once a file download is started. You may also add instructions that will appear above the browser window.

Name	browse-for-download
Parameters	(url: string, instructions: string)

Example

context.api.emitAndWait('browse-for-download', url, instructions);

Open Knowledge Base

Intruct Vortex to open the Knowledge Base tab to a specified wiki page.

Name	open-knowledge-base
Parameters	(wikiId: string)

Example

context.api.emitAndWait('open-knowledge-base', wikiId);

Internal Events

As these events are not intended to be used by 3rd party developers (and can easily be misused) they are not fully documented here.

• report-feedback
• report-log-error
• start-quick-discovery
• start-discovery
• cancel-discovery
• await-activation
• quickbms-operation
• set-plugin-list
• select-theme
• show-modal
• refresh-main-page
• did-update-masterlist
• apply-settings
• edit-mod-cycle
• force-unblock-elevating
• manually-set-game-location
• retrieve-category-list
• request-nexus-login
• request-own-issues
• bake-settings
• refresh-game-info
• refresh-downloads
• plugin-details