Creator's Guide

Table of Contents

1. Welcome
2. How Heliosphere works
3. A quick definition of terms
4. Version numbers
5. Updates
6. Intermission
7. Tagging mods
8. Making variants
9. Extra files
10. Dependencies

Welcome

Welcome to the Creator's Guide. I'm Anna, the developer of Heliosphere. Through this guide, I hope to get you familiar with how Heliosphere works, how it's different than other mod sites, and some best practices for uploading your mods.

If you feel unsure about anything or think there's something I could add to this guide, feel free to tell me in our Discord server, and I'll potentially update this guide.

So, without any more preamble, let's get into the meat of it.

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.

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, let's take a step back and define some terms.

A quick definition of terms

package

The internal term used by Heliosphere for each mod.

variant

A variant of a package. Each package has at least one variant.

version

The smallest unit of a package, housed inside a variant. This is what gets installed on a user's computer.

I know the definition of variant wasn't very helpful there, but the best way I can describe them is by example. For example, think of Kartoffels' texture upscale mods. Some of them are available in 2K resolution or 4K resolution. This is the perfect use-case for variants. Users can either install the 2K variant or the 4K variant. It wouldn't be appropriate to make this an option inside the mod, so separate variants of the same mod are available. Both variants are the same mod, but they have some important distinction between them.

Every mod you create on Heliosphere starts off with one variant, which is automatically named "Default". If your mod doesn't need more than one variant, you can just leave it alone. If your mod does need more than one variant, you can either rename it or delete it and make a new one.

Every mod pack you upload will be uploaded into a variant inside of your package. This may seem complicated, but it allows for clean management of complex mods. The vast majority of mods can just use options inside of their mod pack.

Version numbers

With those terms and explanations out of the way, we can talk about actually uploading. 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).

There are three important things to take away from this:

1. you can't upload the same version number inside the same variant twice
2. new versions should have a higher version number than old versions
3. 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.

Intermission

I hope I haven't made Heliosphere sound overly complicated. For most creators, you'll just make a new mod, fill in the form, and upload a mod pack. Then you'll just upload your updates after. I'm told it's a very intuitive and smooth process. However, there is a lot of complicated technology and systems involved, and it can be helpful to understand how these things work if you ever need them.

If you're ready to move on, I'll explain how things like tagging, extra files, and dependencies work.

Tagging mods

Just like other mod websites, Heliosphere allows you to tag your mods. When adding tags, Heliosphere will show you similar tags and how popular they are. The number on the right side of the autocomplete menu is how many mods are using that tag. I suggest that you use more common tags to make it easier for users to find your mod.

Also like other mod websites, Heliosphere has mod categories. Unlike other mod websites, though, Heliosphere counts categories as tags. This means your mod can be under multiple categories, and you can search for mod categories exactly the same as you can for tags.

Heliosphere also uses tags for race and gender specifications, though those are hidden from the tag list to not clutter it. Please avoid generic tags like female, since tags like female-miqote are more useful for users to find mods. There are toggles for these tags available for your convenience.

Making variants

Extra files

Often there are extra files you want to distribute with a mod, like a devkit or a PSD or even the TTMP version of the mod. Heliosphere allows you to upload these files as extra files.

From the edit page for your mod, switch to the Versions and variants tab, and then use the blue upload button next to a version to upload extra files.

Extra files are associated to a particular version. Due to this, if, for example, a new version requires a new devkit, users will be able to download the appropriate devkit for the version they're looking at. When uploading a new version, you will have the option to copy the extra files from a previous version to the new version.

Dependencies

You may specify dependencies that any given version of your mod requires to function properly. Like extra files, dependencies are specific to each version, and you can copy them from a previous version while you're uploading a new one.

You may specify a text-only dependency, which functions as just a title of the dependency needed. You may also provide a link to the dependency, or you may provide a Heliosphere link to the dependency. If the dependency is a Heliosphere mod, the user will be able to see if they already have it installed.