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.

Searching

Heliosphere's search function has two primary modes: simple and advanced.

Simple search

The simple search will go through titles, descriptions, taglines, and permissions, pulling up any mods with matching terms or words.

To use this, simply put your desired search terms in the query box and click "Search".

Note that titles are weighted most heavily, then descriptions, then taglines, then permissions.

Advanced search

Clicking the "Advanced" slider at the top of the screen or the text that says "Enable advanced search" below the main query box will enable advanced search.

The Query box retains its function from simple search, but there are a number of other items added by advanced search.

1. Author: If you know a specific author's name and want to limit your search to only the mods they have made, you can type either their full or partial name here, then select their name from the dropdown menu.

2. Categories: This section specifies which types of mods you want to show up in the search. You may select multiple options at the same time.

3. Race & gender: This section is split into a female and a male section, and allows you to find mods that are compatible with all the combinations of race and gender that your select. Selecting "Any" for either gender will choose all the races for that gender.

4. Tags: You may search for tags that mods have been given by mod authors in this section, and add them as additional filters to your search. Mods with these tags will then appear in the search results.

5. Excluded tags: Any mods with tags that are included in this section will not be included in your search.

6. Affects: If you know the in-game name of the gear item, action, NPC, or emote that you would like to find a mod to affect, then you may add it in here.

7. Subscriber status: This option will allow you to limit your results to include mods only from Heliosphere creators that are subscribers (creators who are supporting Heliosphere by paying a monthly fee), exclude mods from subscribers, or make no distinctions.

8. Order: This option lets you choose how your search results are sorted, in combination with the next option on this list, Direction.

   • Created at will sort mods by the date they were created.
   • Downloaded at will sort mods by when someone last downloaded them.
   • Downloads (all time) will sort mods by their total number of downloads.
   • Downloads (average) will sort mods by their average number of downloads per uploaded version.
   • Similarity will sort mods by how similar they are to your initial search query.
   • Updated at will sort mods by when they were last updated.

9. Direction: Choosing Ascending will, in combination with the Order option, sort the results from lowest to highest; Descending will sort the results from highest to lowest.

   If Order relies on a date, such as "Created at" or "Updated at", Ascending will sort from oldest to newest, while Descending will sort from newest to oldest.

10. Compatibility: Mods that were uploaded or last updated prior to June 28, 2024 will have preceded the release of Dawntrail, the fifth major expansion to Final Fantasy XIV since A Realm Reborn.

    Because Dawntrail made major graphical changes to the engine, any mods that predate the release of Dawntrail will likely not function correctly when downloaded into Penumbra through Heliosphere. These mods will be marked with a warning sign on their thumbnails, both on the main page and in search results.

    

    Selecting "Any" will include these mods in your search results, while selecting "Dawntrail" will exclude them.

11. Number of results: This controls how many search results are shown per page in your search.

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.