Fractal Softworks Forum

Please login or register.

Login with username, password and session length
Advanced search  


Starsector 0.96a is out! (05/05/23); Blog post: Colony Crises (11/24/23)

Author Topic: Learning to Mod  (Read 10024 times)


  • Ensign
  • *
  • Posts: 2
    • View Profile
Learning to Mod
« on: February 18, 2018, 07:50:45 PM »

Hi there!

I'm a new player that's being playing this game for a short while now after seeing Nemo's series on the game.

And now I'm trying to learn how to mod this game. As such I'm trying to learn what goes where in what from an existing mod. From what I've read so far the files that control the planets/stations for a mod would be using the /data/campaign/econ folder where the systems ".json" files would be in.

Now I've tried to look into the mod files of 3 mods mainly Neutrino Corp, Blackrock and Dassault.

All three uses different formats which confused the hell out of me Neutrino has 2 folders (json$ and Java) formats with the system name (one in the normal econ and the other in the src data/scripts/world//systems) , Blackrock im still finding the system files and Dassault uses econ folder method.

I've tried editting the files for Neutrino and Dassault but my changes were never reflected in a new game generated. Does anyone know why?

Btw if i'm not supposed to be learning via this method and there's another method that is less sensitive please do let me know.


King Alfonzo

  • Admiral
  • *****
  • Posts: 668
  • -- D O C T O R --
    • View Profile
Re: Learning to Mod
« Reply #1 on: February 19, 2018, 04:02:52 AM »


Alright, things are a bit more complicated than you give them credit for. What follows is the basics, but it requires a lot of effort, will, practice, and despair. But, if you're willing to put in the work...well then. Are you a real modder? Have you ever caught a good bug, like a, like a real master coder? Well then, have you ever opened up someone else's source folder?


Alright, first thing's first - you are going to need an IDE. Each mod (just about) can be visualized as being in two 'layers' so to speak: the 'JAR' layer, and the 'Default' layer. Here's an example from the Blackrock Drive Yards mod. We'll be using this as the example because it has the Nevermore, which is the best ship in existance, and hence makes this mod infinitely better than all the other mods.

The 'Default' layer is accessible straight from the Blackrock Drive Yards mod folder. These are things can be changed on the fly with a simple text editor (If you do not have notepad+, go get it. Right now. No, I'm serious, actually get it. It's free, and flat out better in everyway to wordpad) or image manipulator (I've heard good things about photoshop and Krita, but I use Paint.NET because I am a pleb). These changes are relatively small - adding a ship, a faction, a weapon, a basic hullmod, sounds and so forth, can be done through editting the files in the 'default' layer. Here's a brief, basic overview of what you can do to fiddle around with the default layer and integrate your mod.

The 'JAR' layer, however, is more complicated, because this essentially tells the game to do much more 'complicated' things. Adding systems, planets, markets to buy stuff, special hullmods that depend on other hullmods, special scripts for weapons and visual effects are all dealt with on the JAR layer. I am calling it the JAR layer, because all of this - adding planets etc. is controlled by the JAR file in the jars folder. The JAR file isn't really a 'file'; it can be visualized more like a winrar folder, except for java. And in order to write stuff inside that jar file, and thus do anything with the JAR layer, you need an IDE.

Here is a tutorial by Kazi on how to download and use the IntelliJ IDE. If you actually know how to code, you can use netbeans. As far as I know it is up to date, but you may have to do some fiddling with specificying the src folder. Now, things will be a little spooky when you load up IntelliJ, but follow Kazi's (and just about everyone else's) suggestion - copy and paste another mod, load that up as a project from existing source and then go in and make changes. I suggest ORA if you plan on making new systems - Tart keeps good notes in his files. Then follow through with build objeect, and that'll write you a jar file.

And then you will learn the meaning of Copy Paste Despair.

But I digress. Before we enter into the jar folder, I'm going to open up the modinfo.json:

If you've read that brief overview above, you'll know what this file does, except these two lines. The first, "jars", tells the game where the jar file is. The second line, "modplugin", tells the game which file to run to activate the mod. The 'jar's line is self explanatory - you are telling the game you have a jar file for it to read. The modplugin line, tells the game where the modplugin file is. What is a modplugin? I'm afraid I can't let you in on that dangerous knowledge until we proceed further into the foul depths of the src folder.

Speaking of which, let's plunge into the jars folder of Whiterock Crack Yards:

Every mod that uses a JAR layer (and that's nearly all of the good ones) uses a fairly rudimentary structure. Some things may be juggled around a bit, but some things remain the same. In this case, we have a jar file - terrible may be it's power - right where Cycerin told the mod_info.json where it was. Above that is the src folder - the IDE turns everything in this folder into the jar file. INTO THE SRC FOLDER...and then into the data folder!

As you can see, there's some things in here that you'd expect to see in the 'Default' layer. Except, they're more complicated than a normal file, because you are physically running a script inside that file. This isn't something you can adjust from a pre-existing file - the incompatible hullmods, or the specialized missile AI, or the really flashy effect scripts live here. For the time being, we don't care about the window dressing, we care about the Rudimentals fundamentals. To the Aimbot Scripts folder!

And here is the modplugin file! It is right where Cyc told the mod_info.json where it is. Note: The directory for THIS file, DOES NOT INCLUDE SRC. This is because the src folder becomes the jar file, and you are telling the computer in the mod_info.json where in the jar file the modplugin is. Hence, the src folder doesn't exist any more. Let's open this up with notepad+. The file is a bit complicated because Cyc has done several things in the plugin that aren't relevent to the current conversion. So I have eliminated them to focus on the important things. All of these are present in one form or another in the ModPlugin:

Woah, that's a lot to process. Let's get to it!

This tells the game or the IDE where this file is. I honestly don't know which, but I think it's the IDE. If this is wrong, this gives a NullPointerException.

These are imports. These tell the game/IDE which files link up with this one. So if this file mentions something in basemodplugin, it needs an import that links to basemodplugin. Without these, the file tries to grab a file that doesn't exist, and causes a NullPointerException. The IDE will usually do this for you if you're doing more in depth work.

public class BRModPlugin extends BaseModPlugin
This tells the game that this file is a class called BRModPlugin, and it is tacked on to the end of the BaseModPlugin. A lot of files are 'tacked on' to other existing files in this way, and a lot of files are public classes. Getting the name wrong here causes a NullPointerException. Everything between the { at the end of this line, to the final } at the bottom of this file is considered to be in a public class "BRModPlugin" file. Getting these {}'s wrong will cause the file to not compile into a jar correctly.  If you're using an IDE, it should catch that these are wrong when you compile.

public static boolean isExerellin = false
This is a 'switch', so to speak. Let's just imagine 'false' is 'off', and 'true' is 'on'. The switch is called isExerellin, and right now it's off. This line appears in every mod in some form or other, because if you plan on putting stations or planets in, you need to run a gen file. The random mode in Nexerellin (Which used to be called Exerellin, and in the code EVERYWHERE it's still Exerellin) however ruins existing gen files and crashes the game. This is involved in a sort of safety catch - if the random mode is running, this switch turns on, the gen file won't work, and the game won't crash.

public static void initBR() {
if (isExerelin && !SectorManager.getCorvusMode()) {
new BRGen().generate(Global.getSector());

This is a Method that checks if the random mode from Nexerellin is running. Specifically - is the Nexerellin Mod even on this computer, followed by are we in Random Mode? If the answer is Yes at the end, then 'return' is triggered, and the initBR file stops there. However, if we don't have Nexerellin installed, or we do and and we don't have Random mode turned on, then it tells the game No at the end, and runs a new BRGen file. So we don't crash the game. Joy! The BRGen file will pop up later, but keep it in mind.

public void onApplicationLoad() {
    isExerelin = Global.getSettings().getModManager().isModEnabled("nexerelin");

public void onNewGame() {

I honestly have no idea what triggers the Overrides. But basically they run when the BRModPlugin file is in the game, and certain things are triggered. Everything in between the {}'s is run when that Override is triggered. The first override triggers when you load up Starsector, and asks itself - Do I have Nexerellin installed? If the answer is yes, then we change isExerellin to true. The second override triggers when you start a new game, and runs the initBR method, written earlier in this file.

PHEW! That's a LOT of WORK for one tiny file! But this file is important - your mod NEEDS this file to run a lot of special things, which you should be able to determine through observation and invesstigation. Further, there's several things in this file you should note:

1. package... Every file has them. Make sure it matches the location of your file.
2. Imports. Every file has them. Make sure they point to the right place.
3. Every NEARLY every file extends another file. When you're poking around other mods, keep an eye on what they extend.
4. When poking around other files in this mod and others, you can track the pathways in which they work. So in this BRModPlugin, we see that we are now on the pathway to BRGen. When looking at other files in a mod, keep an eye out for these pathways, so you can reverse engineer them for your purposes.

Anyway, let's backtrack to the scripts folder...

And now let's go into the world folder, and then the blackrock folder:

Ah. It appears that Obi Wan Kenobi has located our wayward BRGen file. Let us open it, with extreme prejudice, before we are overrun with memes:

Ahoy! Some of these things we've seen before - package, imports, extends, and Methods. But here we can see Cycerin has done his diplomacy Method here like a good man. Some crazy people do this in the ModPlugin file for some unfathomable reason. All mod factions have this in one form or another, otherwise you are destined to start each game as a despicable neutral except to pirates, Junk Pirates, CABAL, and GMDA. It's not exactly vital - you can run a game without this quite easily - but for flavour reasons it's usually good to play around with these. Is your faction at war with the Hegemony? Are they best buddies with the Sindrian Diktat? Who are the KoI that keep popping up in diplomacy methods? It is a mystery.

At the bottom of this file is an Override that runs when the computer is generating the Sector, that is, putting all the systems etc. in. The GetBountyPersonEvent line tells the game that your faction does bounties. That's all, nothing special. The next line tells the game to run the Diplomacy Method, and integrate the faction relationships into the game. And at the very bottom there are two lines that tells the game 'Oh, and add these star systems to the sector k thx'.

Yep, now we're actually getting somewhere juicy.

Let's go back to GAH

Let's dodge this silliness and go into the gneiss folder:

And here is our Gneiss Gen file. Let's go into this file and have a glance what's in it, and I'll point out the particulars. There's quite a bit to process, so here's multiple images:

This is basic stuff - imports, generate, filename that doesn't have an extends (which took me by surprise), and now the beginning of the good stuff:
- A line that adds a starsystem with a name you give it.
- A line that tells the game where this system is in hyperspace. Check here to see if there's a spot for you.
- A line that tells the game what picture should be in the background of the system.

And now things get KERAZY:

A lot of these are self explanatory, and if you pop up the files in starsector-core/data/scripts/world/, Alex has helpfully added annotations so this makes sense. Also, the IDE you're using will also display what all this onesense means. So for instance if you add a planet, the IDE will tell you what each of those numbers and words mean, like which number is the size of the planet, and it's orbit, and the name of the planet, and it's ID, and so on and so forth. Nebulas are a bit more complicated, and you're better off at first copying a vanilla one until you can difure out how to make them yourself. It involves making an actual nebula picture, which you can see in the graphics folder in the Default Layer of all places. I haven't put a Adamantine Gate in there because...I haven't. BUT, you should be able to have a peek in the DMS files for one. Get used to having a peak in all sorts of different mods in order to find that texture / type of station / etc. you want in yours.

Now, let me just pause and quickly leap back in time to here:

See that add MarketPlace file? You need that, and you can copy and paste it with no repurcusions - it's essentially a Method that tells the game to add market place stuff to your Gen file. Just make sure you change the 'package' line at the top of the file so it matches where you copypaste it to, and credit the guy you copied it off. Now we return to the Gneiss gen file, where things get WEIRD:

Yep, this is how markets are added, super modder style - embedded DIRECTLY INTO THE GEN FILE. Which is CRAZY. And it needs that MarketPlace file way back in data/scripts/world/blackrock. The format is addMarketPlace.addMarketPlace (faction id, entity this market is on, stuff that uses this market (So if you go to the moon or the station as well as blackrock, then you use the same market), the name of the market, the size of the market, array (a list of conditions), array (a list of what markets are available), tarriff level);. This, again, will be observable in the IDE.

Finally, to wrap things up is to automactically generate fringe and gas giant jump points, clean up the hyperspace around your system, and you're good to run.

And there you have it - the basics in adding your own system to the Sector. But wait, I hear you exclaim, what if I want to add a thing to an existing system? Well, that requires some minute tweaks. To see how to do that, let's surf on over to the Metelson Mod:

First things first - the imports are a bit weird. Also, we have an annotation here which points to a Metelson_Markets file. This is Azmonds AddMarketPlace file. This major difference with Cycerin's Blackrock is a product of Azmond's coding style / way he compiles. Different modders use different methods and techniques to carry things out, so don't be surprised if things are in different places - just hunker down, look at the imports and follow the pathways. But regardless, when adding a station to an existing system, it's surprisingly simple.

1-Find system
2-Add thing around thing
3-Add marketplace

So, once you've done aaaa~aall of this work in the IDE, compile to make your Jar...and Learn the Pain of Copy Paste Despair. If IntelliJ fails to compile, or an error pops up, then go and fix it. Once you've gotten a Jar that Actually Compiles, open up the game, run your mod, and get used to watching it crash. Go back to the log, fix what's wrong, and continue grinding away, and eventually you'll have your own system in Starsector. And then you will know the relief of having your own planets and stations in the game, getting into fights, invading other stations and so on.

Hopefully this overview (and believe you me, this IS a BRIEF overview) has given you the tools to begin to fail spectacularly realize your dreams. I'm sure other modders will chime in with more in-depth details, (and correct me if I've stated something hilarious wrong which is a good possibility) and if you need help then feel free to ask in the Misc Modding Questions Thread, or check out the Discord Server - it sees more activity than the forums. Finally, always give credit where credit is due, and acknowledge the modder whose mod you originally copied to make yours. Go forth and Mod, you lunatics! Go forth and create amazing empires and beautiful botes!


  • Commander
  • ***
  • Posts: 123
    • View Profile
Re: Learning to Mod
« Reply #2 on: February 19, 2018, 04:36:38 AM »

King Alfonzo,

I'm no modder, but let me just say:

That was amazing, thank you very much for the time and dedication you took to put that together.
You see, Araragi-san, in a way, the supernatural is what's behind the curtain.
Normally, you only need to see what's happening on stage. That's how reality works.


  • Ensign
  • *
  • Posts: 2
    • View Profile
Re: Learning to Mod
« Reply #3 on: February 19, 2018, 03:13:57 PM »

All Hail the King!,

Now I may just need another month to digest the unholy hell that is copy paste and despair.

Sigh it used to be so much more simple back in the good old days of C++....

Now time to go download that IDEwhatdidyoucallthat?.


P.S King's answer should be pinned it was just that awesome.

Johnny Cocas

  • Commander
  • ***
  • Posts: 172
  • Murder Wedges!!
    • View Profile
Re: Learning to Mod
« Reply #4 on: February 19, 2018, 04:22:35 PM »

Somebody pin this or add it to the modding tools/guides list!

Harmful Mechanic

  • Admiral
  • *****
  • Posts: 1340
  • On break.
    • View Profile
Re: Learning to Mod
« Reply #5 on: February 19, 2018, 05:37:08 PM »

All hail the king indeed. That was delightfully comprehensive.

BTW, if you're using DME's system files as a reference, definitely look at the more recent, better commented ones (Besson is probably the golden mix of advanced stuff + well commented). It's ludicrous how much better I got at writing systems over the course of the mod and the files definitely reflect that. A fully-commented system file is definitely something we should think about putting together for the modding resources section.

Definitely use an IDE to work on systems; you really need the full featured set of tools to do them properly.


  • Admiral
  • *****
  • Posts: 3876
  • Quartermaster
    • View Profile
Re: Learning to Mod
« Reply #6 on: February 20, 2018, 03:40:13 PM »

This is why I fell out of modding Starsector for the most part a few years ago - I just didn't have the time to learn how to use an IDE and the fact that other people were just able to make much better content because they knew how to use an IDE, it just wasn't worth the effort.  Those were the simple days where a faction mod was nothing more than a new planet shoved in the Corvus system somewhere and there were no economics.  Maybe one day I'll come back to modding, but in the meantime I'll keep this thread in my back pocket.
« Last Edit: February 20, 2018, 03:44:58 PM by The Soldier »
Quote from: Trylobot
I am officially an epoch.
Quote from: Thaago
Note: please sacrifice your goats responsibly, look up the proper pronunciation of Alex's name. We wouldn't want some other project receiving mystic power.

A Random Jolteon

  • Commander
  • ***
  • Posts: 156
    • View Profile
Re: Learning to Mod
« Reply #7 on: March 11, 2018, 06:25:30 PM »

Holy...Okay someone give Aflonzo a freaking Medal!
Hi. I exist. Bye.