Introduction

Heliosphere is a mod platform for FINAL FANTASY XIV that integrates directly with a runtime mod loader called Penumbra.

This documentation is split into two parts: one for users and one for creators.

Try looking in the sidebar for any topics you need help with. You can also use the search (magnifying glass) at the top of the page.

Installation

To get the most out of Heliosphere, you can install the companion plugin. This will allow you to receive automatic updates (or just check for them if you don't want it to be automatic) and install mods directly into Penumbra with one click.

Install XIVLauncher

1. Click here to download the latest XIVLauncher installer (or go to their latest release page and download Setup.exe).

2. Launch Setup.exe.

3. Follow the instructions to install, then sign in and launch your game.

Add the Sea of Stars repository

1. Log in to a character, then press Esc and click on "Dalamud Settings" (or use the /xlsettings command).

2. Click the "Experimental" tab at the top of the settings window.

3. Under the third-party repositories section, paste the following URL in the empty text box.

https://raw.githubusercontent.com/Ottermandias/SeaOfStars/main/repo.json

https://raw.githubusercontent.com/xivdev/Penumbra/master/repo.json

https://repo.heliosphere.app/

4. Click the plus (+) button.

5. Click "Save and Close".

Install Penumbra

1. Press Esc and click "Dalamud Plugins" (or use the /xlplugins command).
2. Click "All plugins" and either scroll down to or search for Penumbra.
3. Click on Penumbra, then click install.

Set up Penumbra

Use the /penumbra command and follow the tutorial. You must set a mod directory or mods will not work. If you still would like more help after the tutorial, you can read the unaffiliated guide for more information.

Install Heliosphere

1. Follow the same procedure as installing Penumbra, but install Heliosphere instead.
2. Open the first-time setup and follow the prompts.

How Heliosphere works

Heliosphere works differently than other mod websites. Like other mod websites, it lets you, as a creator, upload your mods in two formats: TTMP and PMP. However, unlike other mod websites, Heliosphere will then process your uploaded mod.

Without going into too much technical detail, Heliosphere unpacks your mod, checks to see if the files inside have already been uploaded, then compresses and uploads any new files to its own storage servers.

After the website processes your mod, users will be able to download it either as a PMP on the website or directly into Penumbra via the in-game plugin. Both methods use the same behind-the-scenes logic: all the files are individually downloaded and decompressed and then reconstructed into one coherent mod pack.

Heliosphere will never offer TTMP downloads. However, most people want TTMPs so they can import into TexTools. TexTools has added PMP support in their Dawntrail release, which means you are able to import Heliosphere mods into TexTools (and export PMPs out of it)!

One of the many benefits of this system is that you can offer streamlined mod updates just by uploading a new version of your mod. Users can get those updates automatically if they choose to, and otherwise, they're only a click away. When they receive these updates, they are only downloading new or changed files instead of redownloading the entire mod.

If this is sounding good to you so far, you'll probably like Heliosphere's way of doing things. However, the rabbit hole goes deeper, as Heliosphere has some more-complex systems available to creators. In order for you to best understand how to use Heliosphere, we'll take a step back and define some terms in the next section.

Variants versus versions

An important idea on Heliosphere is the difference between variants and versions.

• variant
  • one of potentially several alternative installs of a single mod
• version
  • one of potentially several iterations of a single variant

The difference between them is more easily explained by example.

Suppose you have ported or created an original outfit. If you made several variants of the outfit for different bodies, you might choose to distribute them as individual variants on Heliosphere instead of as options in one large variant.

For another example, suppose you've made upscales of large swathes of the game, and you've done so in 2k and 4k resolutions. It wouldn't make sense to provide both resolutions in the same download, but since they're just different variants of the same mod, you create a 2k and a 4k variant on Heliosphere.

Users can install multiple variants of the same mod and even have multiple variants enabled at the same time. They're just a way to organise your mod without multiple pages for different subclasses of the same mod.

Many creators do not need to use variants. If you don't need this level of control, just ignore variants. Keep the one called "Default" and go about your business as usual.

So what's a version? A version is just an iteration of a variation. In our first example, imagine you had a Bibo variant of your outfit and a YAB variant. Both start at version 1.0.0. Right now, you have a unique 1.0.0 (Bibo) version and a unique 1.0.0 (YAB) version.

If you fix a bug in the YAB variant, you might change the version number in the PMP/TTMP to 1.0.1 and upload the fix to the YAB variant. Now you have three versions: 1 in the Bibo variant and 2 in the YAB variant.

• 1.0.0 (Bibo)
• 1.0.0 (YAB)
• 1.0.1 (YAB)

Lastly, the variant called "Default" is a bit of a special case. It is usually omitted from your mod name, so if you only have one variant, you should usually keep it called "Default".

Version numbers and updates

Version numbers

Heliosphere expects you to version your mods using something called Semantic Versioning. In practice, this just means that your mods will always show up with version numbers like x.y.z (e.g. 1.2.3, 2.0.0).

Importantly, you do not set the version while uploading your mod. You set it while creating it, either in Penumbra or TexTools. Heliosphere just reads the version number out of your mod.

Heliosphere is lenient with your uploads, so if you set the version of your mod pack to 1 or 2.0 or even 1.0.0.0, Heliosphere will probably be able to convert it into an equivalent compatible version number.

There are three important things to take away from this:

• you can't upload the same version number inside the same variant twice
• new versions should have a higher version number than old versions
• you probably don't need to change how you're doing things

Essentially, if you're uploading an update, make sure that you've incremented either the x, y, or z in x.y.z.

Some versioning advice you don't have to follow is that:

• bug fixes should change the z in x.y.z (1.2.3 → 1.2.4)
• new options should change the y in x.y.z (1.2.3 → 1.3.0)
• big overhauls/reworks/redesigns should change the x in x.y.z (1.2.3 → 2.0.0)

Updates

The reason all of this is important is that updates need a higher version number to be recognised by Heliosphere. Importantly, this also means that you should not delete an old version and re-upload it to fix things. Just upload the fix with a higher version number. If you delete the old version and replace it with a different mod pack using the same version number, you'll mess up the auto-updates, and your existing users won't get the fix.

Of course, you can choose to delete the old version and upload a new, higher version with the fix. That will work just fine.

Just in case you were wondering, Heliosphere does need you to upload the whole mod pack for each update. Even though it will screen out all the unchanged files, it's important for determining which files to have users download when they install your mod.

There is an experimental way to do delta updates, which only require you to upload new or changed files. If you would like to help test those, let me know in our Discord.