How to test a game extension

Testing a game extension isn't an exact science but these are some ways to make sure that the extension is going to work on other user's computers as well as make sure that common pitfalls are avoided.

Ways to test

80/20 rule of mod coverage

A game extension is never going to support 100% of mods due to the various mod types available, every game being different and the general complexity of modding.

We recommend taking the most popular mods for the game on Nexus Mods (not including reshades or executable installers) and just making sure they work. Not all types of mods will necessarily work but if only a small percentage of the most popular mods work, that isn't good for the users of Nexus and generally causes more complaints and support issues.

If that's the case, come talk to us in Discord (#vortex-dev is ideal for extension chat) and we can help point in the right direction when it comes to code snippets or how to tackle the problem.

A clean game install

It's always good practice, even if slightly awkward, to test the extension on a clean game install and potentially across multiple game stores. This can highlight issues like folders not being created, paths not being relative, games not being discovered.

Another user's computer

The next stage after a clean game install is to test on another user's machine where possible, a friend or colleague can help massively with diagnosing common issues. You will have a greater chance than just doing the above to find incompatibilities with folders and stores. To send an extension to another user to test, follow the same steps in How to package a game extension to make sure your archive and files are structured and formatted correctly. You DO NOT need to upload to Nexus at this point, just send the user the archive and ask them to extract it to a folder within the %APPDATA\Vortex\Plugins folder.

For example

My extension is within an archive called game-name-0.1.0.zip and I send that to a friend to try it out.

• Press Windows Key + R to bring up the Windows Run box and enter %APPDATA%\Vortex\Plugins
• Extract the game-name-0.1.0.zip archive into a folder
• You'll end up with %APPDATA%\Vortex\Plugins\game-name-0.1.0 that looks something like this inside

Start Vortex and it will load the extension the same as if it was downloaded.

Common review failures

These are common problems that we come across during game extension review that will cause them to fail

Incorrect Packaging

The top 3 packaging issues we see are:

• Single nested folder as root (all files inside of a single folder in the archive)
• Incorrect version (not being semantic)
• Incorrect gameart (wrong size, containing text)

Please read How to package a game extension for everything you need to know to fix these issues.

Absolute Paths

In order for the extension to work across any computer, all paths need to be relative and not include absolute paths. A path to a mod folder like c:\games\starfield\mods generally won't be the same on another user's computer (as they might use a different drive or a different games folder) and so paths need to be relative to the game folder that the extension is managing such as .\mods.

Not creating needed folders

Vortex doesn't create folders by default when paths are defined. In the example above, the mods folder within c:\games\starfield isn't a default game folder and so can't be relied upon to exist.

The best way to make sure that Vortex doesn't try to access a folder that doesn't exist is to create any folder that is referenced by the extension. At a minimum there is what queryModPath is defined as and also any extra mod types that have been defined tend to have their own paths. The fs.ensureDirWritableAsync() function can be used to make sure paths exist. See this example to see how ensuring a mods folder exists within the game root (discovered) folder.

async function setup(api: types.IExtensionApi, discovery: types.IDiscoveryResult): Promise<void> {

    try {
        // make sure the folder exists
        await fs.ensureDirWritableAsync(path.join(discovery.path, 'mods'));

        return;        
    } 
    catch (error) 
    {
        // show error in vortex ui
        api.showErrorNotification('Failed to setup extension', error);

        throw error;
    }
}

Dependencies

Some games have tools or mods that are needed in order for the majority of mods to work. These can include script extenders (SFSE for Starfield, SKSE for Skyrim) or tools (LSLib for Baldur's Gate 3). During testing, if you find that a dependency like this is needed, then inform the user that they need, or more than likely will need, it in order for mods to work.

It doesn't have to be a complicated download and update system like some of the bigger extensions have (as nice as they are) but from a users perspective, they will download the extension and expect mods to work or be given all the information necessary to get them to work.

A simple notification with what needs to happen is enough to get started.

Example

api.sendNotification({
    id: 'mod-required',
    type: 'warning',
    message: 'This tool is required by most mods',
    allowSuppress: true,
    actions: [{
        title: 'Download',
        action: () => util.opn('https://www.reshade.me/').catch(err => undefined);
    }],
});