Difference between revisions of "Packaging extensions for Vortex"

From Nexus Mods Wiki
Jump to: navigation, search
 
(One intermediate revision by the same user not shown)
Line 9: Line 9:
 
*it has to be uploaded to [https://www.nexusmods.com/site https://www.nexusmods.com/site]  
 
*it has to be uploaded to [https://www.nexusmods.com/site https://www.nexusmods.com/site]  
 
*it has to be added to the correct category  
 
*it has to be added to the correct category  
*it can only have a single file under "main files"  
+
*it can only have a single file under "main files" (there are exceptions, see under "Advanced: Supporting multiple versions")
 
*it must use semantic versioning (3 numbers: major.minor.patch, see [https://semver.org/ https://semver.org/])  
 
*it must use semantic versioning (3 numbers: major.minor.patch, see [https://semver.org/ https://semver.org/])  
 
*it has to be manually reviewed by us  
 
*it has to be manually reviewed by us  
Line 73: Line 73:
  
 
Extensions have to be added to the Category "Vortex -> User Extensions"
 
Extensions have to be added to the Category "Vortex -> User Extensions"
 +
 +
== Advanced: Supporting multiple versions ==
 +
 +
Sometimes your extension will use features only introduced after a certain release of Vortex or you have one version of your extension that works with an older release and an update that only works with a newer one.
 +
 +
To support this you can include the text "Requires Vortex <version range>" (important: no spelling mistakes!) in the description text for the file.<br/> The version range can be a semantic versioning range as described (for example) here:&nbsp;[https://devhints.io/semver https://devhints.io/semver]
 +
 +
Most commonly you'll want to do something like "Requires Vortex >=1.2.0" to signify: "all versions starting with 1.2.0".<br/> <br/> If you need to support two different ranges of versions (e.g. you have one version of your extension that works only with 1.1.x and one that works only with 1.2.x and newer) your extension can have two main files, one that says "Requires Vortex ~1.1.0" and the other saying "Requires Vortex >=1.2.0".
 +
 +
[[File:Extension version ranges.png|650x268px]]
 +
 +
<br/> This is the only exception where you can have multiple main files for an extension and it will only work correctly if the version ranges you set are mutually exclusive.<br/> If you have one extension that says "Requires Vortex >= 1.1.0" and one "Requires Vortex >=1.2.0" you're risking that users with Vortex 1.2 will still install the version intended for 1.1. (because >=1.1.0 also includes 1.2.47)
  
 
[[Category:Vortex]] [[Category:Development]]
 
[[Category:Vortex]] [[Category:Development]]

Latest revision as of 11:26, 30 April 2020

Overview

This article is for those who have created an extension (or a translation or theme) for Vortex and want to upload it for others to enjoy.

The easiest way for users to find and install extensions is through the built-in dialog. For your extension to be listed there a couple of things have to be fulfilled:

  • it has to be packaged in the correct way (see below)
  • it has to be uploaded to https://www.nexusmods.com/site
  • it has to be added to the correct category
  • it can only have a single file under "main files" (there are exceptions, see under "Advanced: Supporting multiple versions")
  • it must use semantic versioning (3 numbers: major.minor.patch, see https://semver.org/)
  • it has to be manually reviewed by us

This last step means that after uploading your extension it may still take some time before it will be offered within Vortex.

 

Translations

Translations need to be packaged such that on the top level you have a directory with the two letter iso code for the language, optionally postfixed with the two letter country code. Directly inside that directory you include the translation files in json format.
You can have additional files like readmes and license files in the base directory but we advice against including additional directories. Vortex will ignore any directory which isn't named like an iso language code and there has to be exactly one of those (two shalt thou not count, neither shalt thou count zero, excepting that thou then proceedeth to one. Three is right out.)

 So for german it could look like this:

/
|--> readme.txt
|--> de
  |--> common.json

For swiss german it would be

/
|--> readme.txt
|--> de-CH
  |--> common.json

 

The code will determine the language name as the user selects it and will also control things like date and number formats and lexical ordering.

Translations need to be added to the Category "Vortex -> Translations"

Fun fact: The swedish alphabet contains the same umlauts ä and ö also found in the german one but while the german umlauts are sorted as if they were ae, oe and ue, the swedish ä and ö are at the end of the alphabet. Stuff like this makes it impossible to define a universal order for all known letters. Bet you didn't know that. Bet you didn't care to.

Themes

Themes should contain a single subdirectory containing your scss files. The name of that directory will be used in the dropdown where users choose the theme.
You can include multiple subdirectories, each of which will appear as a separate theme for the user to pick from.
Here too you're welcome to include further files (readme, license, ...) but any directories is expected to contain a valid theme.

Example:

/
|--> readme.txt
|--> My Fancy Theme
  |--> variables.scss
  |--> style.scss

Themes have to be added to the Category "Vortex -> Themes"

Extensions

Extensions (including game extensions) need to contain at least an index.js and an info.json file. Both need to be placed on the top-level of the archive. If you include further assets or libraries (libraries that aren't baked/webpacked into the index.js) you are free to arrange them into subdirectories of course.

Example:

/
|--> readme.txt
|--> index.js
|--> info.json
|--> assets
  |--> fancy.jpg
  |--> icon.svg

On the topic of the info.json file: Please make sure you specify the exact same version number during upload that you have set in info.json and that the version is in semantic versioning format.
Also: Please try to avoid changing the name of an extension (inside the info.json file) as much as possible, definitively don't put the version number into the extension name.

Extensions have to be added to the Category "Vortex -> User Extensions"

Advanced: Supporting multiple versions

Sometimes your extension will use features only introduced after a certain release of Vortex or you have one version of your extension that works with an older release and an update that only works with a newer one.

To support this you can include the text "Requires Vortex <version range>" (important: no spelling mistakes!) in the description text for the file.
The version range can be a semantic versioning range as described (for example) here: https://devhints.io/semver

Most commonly you'll want to do something like "Requires Vortex >=1.2.0" to signify: "all versions starting with 1.2.0".

If you need to support two different ranges of versions (e.g. you have one version of your extension that works only with 1.1.x and one that works only with 1.2.x and newer) your extension can have two main files, one that says "Requires Vortex ~1.1.0" and the other saying "Requires Vortex >=1.2.0".

Extension version ranges.png


This is the only exception where you can have multiple main files for an extension and it will only work correctly if the version ranges you set are mutually exclusive.
If you have one extension that says "Requires Vortex >= 1.1.0" and one "Requires Vortex >=1.2.0" you're risking that users with Vortex 1.2 will still install the version intended for 1.1. (because >=1.1.0 also includes 1.2.47)