Events

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

Note: 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

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

Event List

mods-enabled

Name

mods-enabled

Parameters

mods	string[]
enabled	boolean
gameId	string

Function

api.events.on

Triggered

whenever mods got enabled or disabled in the current profile

gamemode-activated

Name

gamemode-activated

Parameters

gameId	string

Function

api.events.on

Triggered

whenever the active game was changed (also on start-up)

profile-will-change

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 canceled though because we can’‘t know if/how previous changes can be rolled back

Name

profile-will-change

Parameters

newProfileId	string
enqueue	(cb: () => Promise<void>) => void

Function

api.events.on

Triggered

before Vortex changes profiles (potentially to a different game), usually triggered directly by the user

will-deploy

Name

will-deploy

Parameters

profileId	string
oldDeployment	{ [modType: string]: IDeployedFile[] }

Function

api.onAsync

Triggered

before Vortex deploys mods

did-deploy

Name

did-deploy

Parameters

profileId	string
newDeployment	{ [modType: string]: IDeployedFile[] }

Function

api.onAsync

Triggered

after Vortex finishes a deployment

will-remove-mod ^{(Requires Vortex >= 1.3.15)}

Name

will-remove-mod

Parameters

gameId	string
modId	string

Function

api.onAsync

Triggered

before a mod is removed (irrespective of whether it was enabled in the active profile or not)

did-remove-mod ^{(Requires Vortex >= 1.3.15)}

Name

did-remove-mod

Parameters

gameId	string
modId	string

Function

api.onAsync

Triggered

after a mod is removed (irrespective of whether it was enabled in the active profile or not)

added-files

Name

added-files

Parameters

profileId	string
newFiles	Array<{ filePath: string, candidates: string[] }>

Function

api.onAsync

Triggered

when Vortex discovers new files were created in the games mod folder that may belong to one of the mods managed by Vortex. The "candidates" lists the ids of mods that _may_ be where the file belongs.

mod-enabled

Name

mod-enabled

Parameters

profileId	string
modId	string

Function

api.events.on

Triggered

when a mod got enabled

mod-disabled

Name

mod-disabled

Parameters

profileId	string
modId	string

Function

api.events.on

Triggered

when a mod got disabled

mod-content-changed

Name

mod-content-changed

Parameters

gameId	string
modId	string

Function

api.events.on

Triggered

Vortex determined that files it deployed were modified or removed

will-purge

Name

will-purge

Parameters

Function

api.events.on

did-purge

Name

did-purge

Parameters

Function

api.events.on

Command List

Commands as such are conceptually very similar to regular api functions but allow multiple (or no) listeners. This loose coupling makes them more appropriate for situations where an extension interacts with another extension where you can’t/don’t want to rely on the other extension actually being loaded.

start-download-url

Name

start-download-url

Parameters

url	string
fileName	string

Function

api.events.emit

show-balloon

Name

show-balloon

Parameters

title	string
content	string

Function

api.events.emit

deploy-mods

Name

deploy-mods

Parameters

callback	(err: Error) => void
profileId ?	string
progressCB ?	(text: string, percent: number) => void

Function

api.events.emit

deploy-single-mod

Description: You can not usually deploy a single mod safely because it would ignore conflicts and such There are very few exceptional situations where this is possible

Name

deploy-single-mod

Parameters

gameId	string
modId	string
enable ?	boolean

Function

api.emitAndAwait

purge-mods-in-path

Description: 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

Function

api.emitAndAwait

purge-mods

Name

purge-mods

Parameters

allowFallback	boolean
callback	(err: Error) => void

Function

api.events.emit

start-install

Description: start installing an archive as a mod

Name

start-install

Parameters

archivePath	string
callback	(err: Error, modId: string) => void

Function

api.events.emit

start-install-download

Description: start installing a file downloaded through vortex as a mod

Name

start-install-download

Parameters

downloadId	string
allowAutoEnable	boolean
callback	(err: Error, modId: string) => void
forceInstaller	string

Function

api.events.emit

remove-mod

Description: remove a mod

Name

remove-mod

Parameters

gameMode	string
modId	string
callback	(err: Error) => void

Function

api.events.emit

create-mod

Description: create an empty mod

Name

create-mod

Parameters

gameMode	string
mod	IMod
callback	(err: Error) => void

Function

api.events.emit

update-categories

Name

update-categories

Parameters

gameId	string
categories	{ [id: string]: ICategory }
isUpdate	boolean

Function

api.events.emit

check-mods-version

Name

check-mods-version

Parameters

gameId	string
mods	{ [id: string]: IMod }
forceFull	boolean

Function

api.events.emit

nexus-download

Description: Download a file from Nexus Mods

Name

nexus-download

Parameters

gameId	string
nexusModId	number
fileId	number

Function

api.emitAndAwait

endorse-mod

Description: Endorse a mod on Nexus Mod

Name

endorse-mod

Parameters

gameId	string
modId	string
endorsedStatus	EndorsedStatus

Function

api.emitAndAwait

endorse-nexus-mod

Description: Endorse a mod on Nexus Mods. Unlike with “endorse-mod”, in this command you specify the nexus mod id so technically the mod doesn’t have to be installed but obviously the site will refuse the endorsement if the user has never downloaded the mod.

Name

endorse-nexus-mod

Parameters

gameId	string
nexusModId	number
version	string
endorsedStatus	EndorsedStatus

Function

api.emitAndAwait

submit-feedback

Name

submit-feedback

Parameters

title	string
message	string
hash	string
feedbackFiles	string
anonymous	boolean
callback	string

Function

api.events.emit

mod-update

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

Name

mod-update

Parameters

gameId	string
modId	string
fileId	string

Function

api.events.emit

open-mod-page

Description: Open the website for the mod. The “source” parameter specifies where we got the mod from, which is required to figure out where the site is. Without extensions, only “nexus” is supported as the sourc.

Name

open-mod-page

Parameters

gameId	string
modId	string
source	string

Function

api.events.emit

import-downloads

Description: Instructs Vortex to copy the listed files into the Vortex downloads folder (for the active game)

Name

import-downloads

Parameters

filePaths	string[]

Function

api.events.emit

remove-download

Description: Delete the specified download

Name

remove-download

Parameters

downloadId	string

Function

api.events.emit

pause-download

Description: Pause a download

Name

pause-download

Parameters

downloadId	string

Function

api.events.emit

resume-download

Description: Resume the specified download. The callback will be called once the download finishes or failed.

Name

resume-download

Parameters

downloadId	string
callback ?	(err: Error, downloadId: string) => void

Function

api.events.emit

start-download

Description: Start a download.

Name

start-download

Parameters

urls	string[]	Multiple urls can be specified to download from multiple sources or to have a fallback if one doesn't work, however as of Vortex 1.3 we only use the first.
modInfo	any	Meta information to be stored with the archive
fileName ?	string	Initial file name to use for the file download. If unset, will be deduced from the url
callback ?	(err: Error, id: string) => void
redownload ?	RedownloadMode	Decides how Vortex acts if a file with the same name has already been downloaded.

Function

api.events.emit

trigger-test-run

Description: Trigger validity checks that find problems with the setup of Vortex or the game.

Name

trigger-test-run

Parameters

eventType	string
delay	number	debouncer timeout to prevent the check from running too frequently, harming performance

Function

api.events.emit

install-extension

Description: Install a Voretx extension

Name

install-extension

Parameters

extensionInfo	IExtensionDownloadInfo

Function

api.emitAndAwait

browse-for-download

Description: Opens an embedded browser to the specified url that closes as soon as the user selects a file download

Name

browse-for-download

Parameters

url	string
instructions	string

Function

api.emitAndAwait

open-knowledge-base

Description: Open the Knowledge Base tab to a specified wiki page.

Name

open-knowledge-base

Parameters

wikiId	string

Function

api.events.emit

autosort-plugins

Description: Run LOOT sort operation. Only has an effect if the active game is a gamebryo game.

Name

autosort-plugins

Parameters

manual	boolean	Whether the user actively invoked the sort
callback	(err: Error) => void

Function

api.events.emit

show-main-page

Description: Change the main navigation page

Name

show-main-page

Parameters

pageId	string

Function

api.events.emit

quick-launch

Description: Start the primary executable (game or tool) for the active game

Name

quick-launch

Parameters

Function

api.events.emit

Internal Event List

If you monitor the event emitter in Vortex you may see the following events emitted or handled. We’re not documenting them because they are intended only for internal use. Please do not use them in extensions, if you actually have a use case for any of these, please contact us. Since we don’t consider these events part of the public API we may be changing them at any time without notice or mention in the changelog.

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

Events

Contributing

Interacting with events

Event List

mods-enabled

gamemode-activated

profile-will-change

will-deploy

did-deploy

will-remove-mod (Requires Vortex >= 1.3.15)

did-remove-mod (Requires Vortex >= 1.3.15)

added-files

mod-enabled

mod-disabled

mod-content-changed

will-purge

did-purge

Command List

start-download-url

show-balloon

deploy-mods

deploy-single-mod

purge-mods-in-path

purge-mods

start-install

start-install-download

remove-mod

create-mod

update-categories

check-mods-version

nexus-download

endorse-mod

endorse-nexus-mod

submit-feedback

mod-update

open-mod-page

import-downloads

remove-download

pause-download

resume-download

start-download

trigger-test-run

install-extension

browse-for-download

open-knowledge-base

autosort-plugins

show-main-page

quick-launch

Internal Event List

will-remove-mod ^{(Requires Vortex >= 1.3.15)}

did-remove-mod ^{(Requires Vortex >= 1.3.15)}