There have been a number of these guides over the years but time passes, so here's one current for *checks watch* 2024.
Table of Contents1.
Installing Mods2.
Assigning more RAM3.
Updating JavaGreetings, StarfarerJust 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 ![Wink ;)](https://fractalsoftworks.com/forum/Smileys/default/wink.gif)
This will take 5 - 20 minutes, depending on your download speed and familiarity with computers.
1. Installing ModsStep 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)
![](https://i.imgur.com/UfhnkQT.png)
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.
MacOS Note: Move your Starsector app to the Applications folder to avoid permissions issues!
Note: There are three primary places to find mods. Yes, it's pretty chaotic and old-school here.
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.
2. Assigning more RAMStarsector 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 JavaStarsector 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 8Step 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.zipStep 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:
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.0Modded troubleshooting:
https://fractalsoftworks.com/forum/index.php?topic=10931.0Keep 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
![Smiley :)](https://fractalsoftworks.com/forum/Smileys/default/smiley.gif)
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".
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.