Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[Wispborne]

There have been a number of these guides over the years but time passes, so here's one current for *checks watch* 2024 2025.

Table of Contents
1. Installing Mods
2. Assigning more RAM
3. Updating Java

Greetings, Starfarer

Just starting to add mods to Starsector?
Added a few mods and are wondering if there's anything else you should do?
Got a PermGen or OutOfMemory crash?
Game suddenly slowing down after battles?

It takes less time to read this carefully than it does to fix a mistake caused by skimming

This will take 5 - 20 minutes, depending on your download speed and familiarity with computers.

There are three primary places to find mods. Yes, it's chaotic and old-school.
  The Index. Mod authors request to have their mod added here: https://fractalsoftworks.com/forum/index.php?topic=177.0.
  Modding Subforum. Contains a mix of mods and other random posts: https://fractalsoftworks.com/forum/index.php?board=3.0.
  Unofficial Starsector Discord. The #mod_updates channel contains some mods and betas not found on the forum: https://fractalsoftworks.com/forum/index.php?topic=11488.0.


Option A: Use a Mod Manager
There are, as of March 2025, two updated mod managers that support installing mods, changing RAM, and updating Java.

TriOS - Changing RAM & updating Java only supported on Windows.
MOSS - All features supported for Windows, MacOS, and Linux.

Both of these work alongside manual mod management and even alongside each other; there's no virtual file systems or anything like that.

Option B: Do it manually
1. Installing Mods

Step 0. If you are updating from a previous version of the same mod, delete (or move) the old mod folder first. Otherwise, there is a chance it will crash when loading.

Step 1. To install a mod, download it and unzip it into the "mods" directory.
  A mod's folder path must look like this: "<starsector>/mods/<mod folder>/mod_info.json". Ensure the mod doesn't have an extra folder. For example, "mods/LazyLib/LazyLib" has an extra folder and won't show up in game.

• On Windows, it's in the Starsector installation directory (default: C:\Program Files (x86)\Fractal Softworks\Starsector\mods).
• On Mac, it's right inside the application package - right-click on the application and select "Show Package Contents" to see it.
• On Linux, it's in the starsector directory.

You can then select which mod(s) you want to run with in the Starsector launcher.


Incorrect due to nested/doubled folders (the mod will not appear in game launcher)


Correct, no nested/doubled folders


Note: When updating to a new mod version, always remove the old mod folder first!
  Many crashes are caused by replacing the old folder but not deleting old files.

Note: Some mods use .rar or .7z instead of .zip. You need a free program such as 7-zip (https://www.7-zip.org/download.html) or, for MacOS users, Keka (https://www.keka.io/en/) to extract them.

Note: MacOS users, move your Starsector app to the Applications folder to avoid permissions issues!


2. Assigning more RAM

Starsector has a limit on how much RAM it can use and adding mods can quickly hit that limit, causing crashes.

Step 1. To assign more RAM to Starsector, follow this guide: https://fractalsoftworks.com/forum/index.php?topic=8726.0.
The process has not changed since it was written and is as important today as it was then.


Note: RAM and VRAM are different. RAM is something you can buy more of and install yourself on most PCs. VRAM, however, is part of your graphics card and cannot be upgraded without buying a new GPU. Starsector automatically assigns VRAM as needed and we do not need to do anything with it.


3. Updating Java

Starsector comes with Java 7 and it runs well on that. However, mods use additional system resources and updating to Java 8 improves modded game stability and performance.
- This updates only Starsector's version of Java (not Windows's) and is fully reversible.
- JRE (Java Runtime Environment) typically means the same thing as Java.
- Starsector 0.98a will use Java 17 instead of Java 7 when it is released, making this step obsolete. Java 17 is expected to have about the same performance as Java 23.

Alternate instructions for Java 23, which has better performance than Java 8, may be found here: https://fractalsoftworks.com/forum/index.php?topic=29320.0
If you use Java 23, then there is no need to follow the rest of the Updating Java step.

Replacing Java 7 (default) with Java 8
Step 1. Go to your Starsector install and rename the "jre" folder to "jre7-backup".
      MacOS users: the "jre" folder is called "Home", so use that instead of "jre", and is located in "Starsector.app/Contents".
      Linux users: the "jre" folder is called "jre_linux", so use that instead of "jre".

Step 2. Download one of the following:
        Note: all are the same "JRE 8 v271".
      - Windows .zip (71 MB) https://github.com/wispborne/JRE/releases/download/jre8-271/jre8-271-Windows.zip
      - Windows .7z (48 MB, requires 7zip or equivalent) https://github.com/wispborne/JRE/releases/download/jre8-271/jre8-271-Windows.7z
      - Linux: https://github.com/wispborne/JRE/releases/download/jre8-271/jre8-271-Linux-x64.tar.gz
      - MacOS: https://github.com/wispborne/JRE/releases/download/jre8-271/jre8-271-MacOS.zip

Step 3. Extract that into your game folder so you have a folder named "jre". You'll now have both "jre" containing Java 8 and "jre7-backup".

Mac/Linux users, make sure to substitute the folder name as mentioned in Step 1.

Step 4. Read the Potential Issues section below (your game+launcher may be zoomed in/off-center).

Step 5. Launch the game as normal.


Potential issues
- Game+launcher is zoomed in/off-center.
    Fix: Right-click Starsector, Properties, Compatibility, Change high DPI settings, tick checkbox for "Override...Scaling performed by Application".
    This is caused by the game or JRE not handling Windows scaling properly.
Screenshot:

Spoiler

[close]

Note: We are using a specific version of Java 8 for a reason. I do not recommend using the most recent patch of Java 8, as it requires an extra step to make it work and doesn't seem to have any significant benefits.


Done!

Here are some useful links to hold on to.
Vanilla troubleshooting: https://fractalsoftworks.com/forum/index.php?topic=2106.0
Modded troubleshooting: https://fractalsoftworks.com/forum/index.php?topic=10931.0

Keep in mind that many things on the forum are outdated, even pinned posts, so make sure to check the Last Edited Date before following something.
For example, the pinned Newbie Guide Thread was last updated in 2013 and contains outdated gameplay information!
Oh, and avoid Beyond The Sector, it'll kill your save eventually

Have fun!


FAQ (hidden to make the guide seem less scary at a glance)

Spoiler

How do I change mod load order?
This ain't Skyrim; 99.5% of the time, you don't need to change load order.
There are few enough mods, and mod authors work well enough together, that any mod conflicts are automatically sorted for you.
The name (not the id) of the mod determines the load order; that's why GraphicsLib's name in the game launcher is "zz GraphicsLib".

[close]

Changelog

Aug 2024
- Added link to Java 23, as it has proved stable.

Oct 2023
- Added screenshots for nested mod folders.

Sept 2023
- Added a screenshot for the Windows scaling fix.

Early March 2023
- Fixed the MacOS Java 8 download, which was missing a crucial Mac-only file.

[close]

[Alex]

Moved to Mods and stickied. Great stuff, thank you for putting this together!

[eidolad]

This is a great guide!  I really like the idea of updating the JRE to help the game run more stably.

a) I generally load a ton of large mods so in my case, having 32GB ram, I updated my vmparams with:  -Xms8192m -Xmx8192m
(even so, eventually the game begins to stutter (memory leak/constant JVM garbage collection?  Haven't bothered to check.  I'm not expected modded games to be perfect memory managers) after a few hours and I have to exit/rerun.  I'm really interested to see if the later jre helps)


b) Would you mind posting the checksum values that you expect for those jre files from your github?

Here is what I have downloaded, (using git bash md5sum):
$ md5sum jre8-271-Windows.7z
b48d846d43f97a97ab4c7ae490685485 *jre8-271-Windows.7z

notes:

I was trying to download the official JRE 8 v271, but Oracle wants me to create an account and even so, the download wasn't for a .7z but an exe (which isn't helpful).  I generally don't like to download executable code from random githubs (no offense meant at all).  Because hackers gonna hack.

[Wispborne]

I was trying to download the official JRE 8 v271, but Oracle wants me to create an account and even so, the download wasn't for a .7z but an exe (which isn't helpful).  I generally don't like to download executable code from random githubs (no offense meant at all).  Because hackers gonna hack.

You can go ahead and use the newer Java 8 download, which does not require an account to download but is not from a random github.
https://www.azul.com/downloads/?version=java-8-lts&architecture=x86-64-bit&package=jre#zulu

You will need to add -Xverify:none to your vmparams file or else it will not launch.

[levisthered]

Hello guys I have been a vanilla player for over a year or so and for most of that time have been drooling over all those cool ship mods. today I tried to install a couple, I followed these directions and watched Ashergames video a couple times before i tried. The mods are extracted to the mod folder but the launcher says i have no mods installed. where did i go wrong. Love the game guys thank you
Levi

[Wispborne]

Hello guys I have been a vanilla player for over a year or so and for most of that time have been drooling over all those cool ship mods. today I tried to install a couple, I followed these directions and watched Ashergames video a couple times before i tried. The mods are extracted to the mod folder but the launcher says i have no mods installed. where did i go wrong. Love the game guys thank you
Levi

The most common cause for this is nested folders.

Good: <game folder>/mods/LazyLib/mod_info.json
Bad:   <game folder>/mods/LazyLib/LazyLib/mod_info.json

In the second case, LazyLib won't show up in the game's launcher. To fix it, just move (drag, or use Cut) the second/innermost folder into the first/outer one.

[khiren]

Hi guys, thanks for the video and instructions.

I've done everything that was told in the https://www.youtube.com/watch?v=2pcUZKkgbxY&t=626s&ab_channel=IroncladLion, and I am still experiencing issues with the memory leak. It isn't enjoyable right now. Each time I load the save, it has a memory leak message, and I need to restart and then load the game to play generally until I need to load again.

To re-cap what I've done.
- download java jre-8u271-windows-x64
- Unpack and install it into the appropriate folder within Starsector while keeping the old version as the Jre7 folder.
- The version of the installed jre folder is JAVA_VERSION="1.8.0_271"
- Under settings file which is located in \Fractal Softworks\Starsector\starsector-core\data\config, I've changed following:

• "allowAnyJavaVersion":true
  
• "maxBattleSize":1000

- vmparams file was edited with the following values:

• -Xms8192m -Xmx8192m -Xss2048k -XX:MaxPermSize=512m

My PC configuration is:
https://drive.google.com/file/d/1Oi6l46-ZeKe4PaVW6vjILQgOgvHt-jTN/view?usp=sharing

Mods list:
https://drive.google.com/file/d/1EexQOw3vP0VIQn53r-cYl_UbWL327ZWu/view?usp=sharing

The error message I get:
https://drive.google.com/file/d/1mE7mWjYsp995QBaaXl77DcmDlJrSye3m/view?usp=sharing

Please help, and thanks!

[Wispborne]

@khiren
It's probably simply a problem with one of those mods. There are a few things you can try, though, for dealing with a memory leak.

1. Try installing Console Commands and ClearCommands, then running cSmartClear in the console. It removes "fleet bloat" in saves, and could fix it if the mem leak is caused by a particular fleet. Certainly not a silver bullet, but easy to try out.

2. Try making a new game and seeing if it happens there. If it does, then you can remove a mod, make a new game, and repeat until you figure out which one it is.

3. Disable the warning (at your own risk). https://fractalsoftworks.com/forum/index.php?topic=25654.msg381486#msg381486
Open up data/config/settings.json and set "doRAMandVRAMChecksWhenRunningWithMods" to false.

4. Another thing to try is a more tuned JRE 8, which isn't something I typically recommend unless there's a problem with the recommended one(s), because having everyone using one (or two) simple setups is much easier than multiple complex setups (and also I don't really think this will fix it, honestly, but it's easier than Step 4).
It's on the Unofficial Discord if you search for "Shenandoah Garbage Collector", but if you don't have a Discord account you can search for it here: https://starmodder2.pages.dev/ and get the Google Drive link (which is currently https://drive.google.com/uc?id=1rvygQxNUh8L7W-D5v2ugEEJvT2ht9Sfu&export=download but may change in the future!).

5. It's pretty technically involved, but figuring out the memory leak is how you would try to get the root cause fixed. This was written by LazyWizard.
There's another guide written by Alex here, back when the world was young: https://fractalsoftworks.com/forum/index.php?topic=7690.msg128363#msg128363

LazyWizard's guide (direct link: https://discord.com/channels/187635036525166592/310517733458706442/812831729478795314)

Alright, I'm going to paste a bunch of instructions on how to track down memory leaks. My apologies for the spam.
I use VisualVM (https://visualvm.github.io/), but another common tool is Eclipse's MemoryAnalyzer (https://www.eclipse.org/mat/). Here are the basic instructions for confirming a memory leak in VisualVM (finding one is a little harder if you don't know what's being leaked, but you can probably figure it out by looking through the various tabs).
First you'd want to create the heap dump. You can do this with external tools, but the console mod includes a "dumpheap" command that will create one from within the game. Do this after the memory leak occurs. This will save a .hprof file in your starsector-core folder, which can be massive (it will contain the state of every object in the Java Virtual Machine, and can be multiple gigabytes in size).

Once you have your heap dump, open VisualVM and load the newly created.hprof file. You'll see this screen:

Spoiler

[close]

Click "Summary" in the top left and switch to the "Objects" tab. Then enable the Fields and References views by clicking them along the top of the bar. The view should now look like this:

Spoiler

[close]

Tracking down a memory leak is tricky, but "luckily" the nature of a memory leak in a garbage collected environment means that everything referenced by a leaked object will be retained, as will everything those objects reference, almost always ending with the entire combat engine or campaign sector being leaked. Therefore we can look directly for those two objects and save ourselves a ton of searching.

At the bottom of the screen is a Class Filter input. Since we're hunting a combat memory leak, enter CombatEngine and press enter. CombatEngine is Starsector's internal implementation of CombatEngineAPI. For sector leaks, you'd filter for CampaignEngine, which is the game's implementation of SectorAPI.

If there is a memory leak involving the combat engine, you should see multiple instances of com.fs.starfarer.combat.CombatEngine. Click on them and check the References subwindow to see what's keeping them in memory. In the example image you can see that two Shadowyards scripts (MS_ShikiPiercePlugin and MS_ArmorPiercePlugin) have static references that are keeping the previous combat engine instances in memory:

Spoiler

[close]

[Shogouki]

Hey Wisp, do you know if there's been any consensus as to whether the Java 8 upgrade that you and Alex had people try earlier this year works any better than the one that people had been using for awhile?

[Wispborne]

Hey Wisp, do you know if there's been any consensus as to whether the Java 8 upgrade that you and Alex had people try earlier this year works any better than the one that people had been using for awhile?

It works about the same. The newer JRE 8 has some micro-optimization, bugfixes, and security improvements, but nothing that noticeably affects Starsector (security is important for e.g. servers, not critical for an offline game that only runs trusted code).
On the flip side, the newer JRE requires modifying the vmparams file by hand, unlike the one in this thread, so I will continue to recommend the older one here due to its ease of install.

This one: https://fractalsoftworks.com/forum/index.php?topic=28209.0
claims to increase performance by around 10%. I don't use it myself and consider it more of a "mad scientist" project than a well-tested alternative; it has undergone a series of revisions to fix crashes already for just a small userbase.

[Shogouki]

Hey Wisp, do you know if there's been any consensus as to whether the Java 8 upgrade that you and Alex had people try earlier this year works any better than the one that people had been using for awhile?

It works about the same. The newer JRE 8 has some micro-optimization, bugfixes, and security improvements, but nothing that noticeably affects Starsector (security is important for e.g. servers, not critical for an offline game that only runs trusted code).
On the flip side, the newer JRE requires modifying the vmparams file by hand, unlike the one in this thread, so I will continue to recommend the older one here due to its ease of install.

This one: https://fractalsoftworks.com/forum/index.php?topic=28209.0
claims to increase performance by around 10%. I don't use it myself and consider it more of a "mad scientist" project than a well-tested alternative; it has undergone a series of revisions to fix crashes already for just a small userbase.

Thanks for the info!  I just decided to go with the v271 that you posted and so far it's working well.  I think the only issue that I still have is the memory leaks that happen often when reloading a game but I'm not sure if any Java tweaks will fix that.

[kjolnir]

Thanks for all the folks who did the work here, switching to JRE8 appears to have solved the performance issues I was experiencing post-battle. 

[Zsar]

Pray tell, are there also instructions for updating to the latest Java? (currently 21)

And once done, does that allow writing mods in the appropriate language version (or are there restrictions due to that Janino compiler and/or does that also have to be updated)?

I see people write mods in Kotlin, but to my knowledge, Kotlin (like all JVM languages) can target a wide array of older Java versions by emitting runtime code to emulate missing language features, so that is probably not indicative.

[Wispborne]

Pray tell, are there also instructions for updating to the latest Java? (currently 21)

They exist I'm sure, but it's not something I would link in a pinned post (also I don't know where to find it). There isn't much for performance gains to be had from newer versions (maybe recompiling the game for a newer version would, not sure).

And once done, does that allow writing mods in the appropriate language version (or are there restrictions due to that Janino compiler and/or does that also have to be updated)?

You could, yes. Janino is only used for non-compiled code, so as long as your mod is compiled then you can use up to whatever version of Java the game is running on.

I see people write mods in Kotlin, but to my knowledge, Kotlin (like all JVM languages) can target a wide array of older Java versions by emitting runtime code to emulate missing language features, so that is probably not indicative.

Kotlin can indeed compile down to Java 6 (1.6) bytecode, but support for that has been dropped in the most recent releases of Kotlin, so we're limited to an increasingly old version of Kotlin (and hoping that IDE plugin support for that version is maintained).

Personally, I waffle back and forth on forcing my own mod, Persean Chronicles, to require Java 8. It would be an artificial requirement, as nothing in it actually needs 8, and may cause some drama/discussion since there aren't currently any mods on the Forum that require 8 as far as I know (though PC is a fairly niche mod). But Java 8 is something all modded players should be using, anyway, and sometimes it feels that any increased visibility of it would be worth it (not to mention the benefits to programmers in Java QoL features).

[RealmX]

The following is a powershell script (for windows) for unzipping all mod zip files (in current folder of the terminal) in place without creating new folder that wraps around it. This is useful when downloading multiple mods in a run and ease the tedious task of having to unzip them one by one and then take them out of the newly created folder.

Code

# Get the current directory
$currentDir = Get-Location

# Iterate through all .zip files in the current directory
Get-ChildItem -Path $currentDir -Filter *.zip | ForEach-Object {
    $zipFile = $_.FullName  # Full path of the zip file
    $destinationPath = $currentDir.Path  # Destination is the current directory
    
    # Extract the zip file contents
    Add-Type -AssemblyName System.IO.Compression.FileSystem
    [System.IO.Compression.ZipFile]::ExtractToDirectory($zipFile, $destinationPath)
    
    Write-Host "Extracted: $($_.Name)"
}