File Based Override Instructions

As of Vortex 1.14.0, mod authors can control how Vortex installs their mods by adding a vortex_override_instructions.json file to the root folder of their mod.

This feature has been developed primarily to ensure a mod is installed correctly even if the Vortex game extension is outdated or flawed (incorrect mod type assignment, incorrect file destination, etc).

It should not be used as an alternative to informing the game extension author of any issues with their code - the instructions should ideally be generated automatically by the game extension. This functionality should only be used as an interim fix while waiting for the game extension to update, or when a mod's packaging pattern is too complex for the game extension to install correctly.

The system is using the same IInstruction object array as the custom installers of the game extension.

For more information regarding the different instruction types and overall structure, please refer to this link.

Please Note, at the time of writing this article - generatefile, unsupported, error instruction types can be potentially used maliciously and are therefore disregarded when detected.

Additionally - override instructions are not applied when installing a mod through a collection!

Usage Examples:

Changing Mod Type

Consider a use case where a game extension assigns the wrong mod type to a certain mod, causing it to deploy its files in an incorrect location.

Adding the override file to the root of the mod with the below JSON data will let Vortex know we want to deploy the mod to the game's root directory.

[{ "type": "setmodtype", "value": "dinput" }]

dinput is the mod type id for engine injectors and is available to all game extensions. It will always deploy to the game's root folder.

Vortex will first check if the mod type id is supported for the active game before assigning it.

To find out which mod types are available, the game extension's code should be reviewed; specifically the id assigned during the mod type registration.

e.g. the id of the mod type is the first parameter in any mod type registration call

context.registerModType('dinput', 100, gameSupported, getPath, testDinput, {
    mergeMods: true,
    name: 'Engine Injector',
  });

Changing a mod file's destination

In certain situations you may want to change the location where Vortex deploys some of the files found within the mod's archive. Vortex uses copy instructions specifying the relative path of the file within the mod's archive as the source, and the relative path of where the file should be deployed to in the game's directory as a destination.

[{
  "type": "copy",
  "source": "someDirectory/someFile.txt",
  "destination": "someNewDirectory/someFileRenamed.txt"
},
{
  "type": "copy",
  "source": "someDirectory/someDifferentFile.txt",
  "destination": "someNewDirectoryRenamed/someDifferentFile.txt"
}]

Please note that the destination's relative path is dependant on the mod type assigned to the mod. The system cannot currently be used to deploy one file to the game's directory in "Program Files" and another to the "My Documents" folder for example.

(Well, it can - but that would require a definition for a submodule type instruction and can get extremely complex, this is best avoided)

As this is an array of IInstruction objects, you can add/remove entries as needed; e.g. you can set copy instructions alongside a mod type assignment instruction if needed.

[{
  "type": "copy",
  "source": "someDirectory/someFile.txt",
  "destination": "someNewDirectory/someFileRenamed.txt"
},
{
  "type": "copy",
  "source": "someDirectory/someDifferentFile.txt",
  "destination": "someNewDirectoryRenamed/someDifferentFile.txt"
},
{
  "type": "setmodtype",
  "value": "dinput"
}]

Using an online JSON Lint tool is highly advisable when generating these instructions.