The purpose of this tutorial is to create sort of a 'minimum viable product' when it comes to modding -- a simple mod including all of the facets that normally come to mind when one thinks of a Starsector mod. By the end of this tutorial, you will have a mod with a custom ship, weapon, faction, star system, and associated other creations, as well as a passing familiarity with the concepts and processes involved in implementing these.

First, lets go over what we're gonna need:

  • A plain-text editor: Notepad++ is the standard, and comes highly recommended.
  • A spreadsheet editor for .csv files: If you have a license for Microsoft Excel you can use that, otherwise I recommend downloading Ron's CSV Editor.
  • An art program that supports transparency layers: Adobe Photoshop is the standard, but some people use Krita (which is free) to good effect.
  • The Starsector Ship and Weapon editor.
  • Eventually, an IDE for editing scripts and compiling a .jar file. There are several tutorials on the forums on how to set up your IDE for Starsector modding:

Once we've got those together, we're ready to start working on our mod.

Mod Framework Edit

So, the first thing we need to do is literally create the mod. Navigate to your Starsector install directory, open the /mods/ subfolder, and create a new folder -- title it whatever you want the name of your mod to be. For this tutorial, we're going to call it 'My Mod'.


Once we've done that, we're going to need a mod_info.json file -- this is a JSON formatted text file that tells the game that the mod exists. The easiest way to get a working one is to copy it from another mod so let's go ahead and do that -- mod_info JSONs aren't the sort of thing where you have to worry about intellectual property. Opening up a mod_info.json from an existing mod, it should look something like this:

	'name':'Kadur Remnant',
	'description':'god rest the theocrats. also some pirate stuff',

We're going to throw out some of that stuff, and change the rest. Most of these fields are fairly self-explanatory, but here are some that require special attention:

  • 'id' - This is the ID for your mod. It should be all lowercase and easy to remember, but long enough to be definitely unique. Since we're making a mod called 'My Mod', we're going to make our ID 'mymod'.
  • 'jars' - This will be a reference to your actual compiled code file, once you have one. Since we don't have one yet, we're going to delete the whole line.
  • 'modPlugin' - This will be a reference to your modPlugin java script, once you have one. Since we don't have one yet, we're going to delete the whole line.

Once you're finished, the file should look something like this:

	'name':'My Mod',
	'author':'Some Loser',
	'version':'0.1 prerelease',
	'description':'My Super Cool Mod (original work DO NOT STEAL)',

Save that file in Starsector/mods/mymod (or whatever you named your mod folder)... And that's it! Congratulations, you're done! You've made a mod!


It appears in the mod list and you can select it and run Starsector with it enabled! It won't do anything yet, of course, but we've taken the first step. Give yourself a pat on the back.

Custom Ship Edit

Now that we've created a mod, let's make that mod actually do something! Specifically, let's make it add a custom ship to the game. That's probably what you wanted to learn how to mod to do anyway, right? I bet it was.

For the purposes of this tutorial, we're going to be creating a little shuttle called the Bastard, with a small missile hardpoint and a universal turret. Later, we'll make a custom ship system, hullmod, and weapons for it, but for now it'll just be a ship.

Spriting Edit

The first thing you're going to need is a ship sprite. This should be a .PNG file with a transparent background, saved at 72 pixels/inch (not necessary, but helpful) and in 8-bit color (absolutely necessary), with as little extra 'blank space' around the ship as possible. I'm not going to give a whole treatise on the artistry of making ship sprites (at least partially because I'm not great at it myself) but some important points to remember and useful resources are:

  • Generally speaking, the process most people recommend for creating a ship sprite is:
    • Sketch a silhouette/outline and maybe some blocks of color. Roughly place weapon mounts, engines etc and think about how these will affect gameplay. Don't worry about size too much right now.
    • Bring the sketch into your painting program (if you drew it on paper or whatever and it's not already there), and shrink it down to the correct size, comparing it to ships you want it to be roughly equivalent to. Place actual weapon mounts now, and make sure everything has enough room.
    • Copy or 'kitbash' bits of existing sprites over your outline to get a rough idea of details and shading -- this part is optional, especially if you're a good artist, but usually a good idea.
    • Paint over the kitbashed parts to mesh everything together and make it your own.
  • Starsector sprites are tiny paintings, not pixel art. Well okay, they're kind of pixel art -- really a combination of the two. But generally speaking, you want to be using primarily painting techniques and only doing pixel art to bring out fine details, et cetera, on the finished sprite. You can do darker shading on the edges, but NO BLACK OUTLINES.
  • It's important that ships match the general size and particularly pixel mass of existing sprites in their ship size class. Pixel mass is the total count of nontransparent pixels in the sprite -- you can find this using your painting program's histogram function, and compare it to this list of Starsector sprite pixel masses.
  • David Baumgart, the artist behind the existing Starsector ship sprites, has made quite a few posts regarding his process: YouTube Video Blog Post One Blog Post Two Blog Post Three Blog 'Art' Tag
  • A few other talented modders have also made YouTube videos, in particular I recommend watching MShadowy sketching and all of Tartiflette's videos.

I've gone ahead and made this beautiful sprite, which should have size and pixel mass appropriate for a small frigate-class vessel, about the same size as a Kite:

Mymod bastard

Having done that, let's create a 'graphics/ships' folder and save the sprite there, with an all-lowercase filename starting with your mod prefix (which should be your mod ID if it's short enough, or the first significant word in your mod's name, or something of the like -- ideally more than 4 or 5 characters long) and an underscore. In the end, it should look like this:


Ship Data files Edit

Now that we've created the sprite, we're going to need some data files to tell the game that it's a ship and what stats to give it. First, we're going to create some more folders:


And then we're going to need a line entry in our ship_data.csv for the ship we're making, and a .ship file. Since we don't even have a ship_data.csv file yet, let's copy vanilla's from 'Starsector/starsector-core/data/hulls/', and delete all the lines, just so we have all the columns right. Now, let's go back to vanilla's ship_data.csv and copy a line of stats over from a ship that's fairly close to what we want ours to be. In this case, I'm picking the Kite.


As you can see, I've actually pasted it in twice and prepended a '#' to the second one's name -- I'm going to leave that one there as I edit the top one, so I can compare my stats to the original without opening vanilla's ship_data file again. I'm not going to tell you how to set up your stats, so use the vanilla file and the Ship Data CSV wiki page as references and get to editing. Just make sure you at least change the name and hull id (which should be prefixed with your mod prefix, and all lowercase). In the end, you should end up with something like this:


I've set up the Bastard as a little, speedy, tough-to-kill light crew and cargo hauler -- nothing approaching the efficiency of the Mudskipper or the speed and armament of the Hound, but much more survivable. Now that we've done that, it's time to fire up the Ship and Weapon Editor and make our ship file!

Ship Editor Edit

(Just as a reminder, these instructions are for the Starsector Ship and Weapon Editor from the Starsector forums)

On running the ship editor for the first time, you're going to see a little pop-up telling you to select the Starsector install directory. It's important that you select the root folder here, not 'starsector-core' or anything else. If something goes wrong and your ship editor won't load any ships or weapons, simply delete the .json file in the ship editor directory -- this will reset the settings -- and run the program again.


The first thing you're going to notice once you get into the editor is the whole pile of menu items. Don't panic, we're going to go through them one by one. It's important to do this, by the way -- it's very easy to miss a step here, and could cause some difficult-to-troubleshoot problems down the road. The first thing we're going to do is press 'i' and load in our nice new ship sprite, then press 't' to edit the details:


Then we're going to press 'esc' to close out of the ship details screen, and 'v' to save it. Make sure you're saving it in the 'mymod/data/ships' directory -- the editor might default somewhere weird.

Once we've saved it, let's continue: Press 'c' and set the center of mass (the point the ship turns around) then 'ctrl' and drag out the collision circle -- this needs to fully encompass the ship and it's shields, so don't be afraid to set it a little big. After that, press 's' (and then 'ctrl') to do the same thing with the shield center (and the shield circle). Do that even if the ship you're making doesn't have shields -- some other effects may use it. The shield circle should completely encompass the ship sprite (and ideally some room behind it, for engine flares) and fall entirely within the collision circle.


Once you're done that, it's time to move on the the bounds polygon. Press 'b' to open that menu, then place points with 'shift+leftclick'. You can turn 'mirroring' on and off with the spacebar. Note that the bounds polygon shouldn't be too detailed -- even though my Bastard-class has little hip dips, we can bound it with only five vertices, like so:


Once you're done that, save it again and it's time to do weapon slots. I'm going to trust you to read the hotkeys for that on your own. Important note: Whenever placing a weapon slot it will default to the same size and type as the nearest existing weapon slot, or a Medium Energy Turret if there are no others. For this reason it is extremely important to go over all of your weapon slots after placing them and press 't' while mousing over each one to check (and set, if necessary) the size, type, and turret/hardpoint settings:


Since we don't have any hullmods or special weapons done yet, we're going to skip over those options and move right on to engines. Engines are also fairly straightforward, but some things you'll want to remember are:

  • Just like weapon slots, engine slots default to the same settings as the nearest existing engine or LOW_TECH if there aren't any -- even if you already set the whole ship's tech level to something else. So just like weapon slots, make sure you mouse over them all and press 't' over each one to double-check their settings.
  • 128 is a magic number: Setting 'contrailSize' to 128 in the engine settings will make that engine flare disappear, and only show up when the ship is using its shipsystem. This is useful for things like maneuvering jets -- Open up the vanilla Eagle .ship file in the ship editor and take a look at it for an example.

After creating engines, make sure to save by pressing 'v' before continuing:


And hey! We've got a complete ship! It doesn't have a description or any variants and it won't spawn anywhere, but it does technically exist -- at this point you could theoretically spawn it into the campaign using a console command. In fact, let's test that before we do anything else -- just to make sure we haven't mucked anything up. Load up the game (make sure to check off your mod in the mod list!), start a new campaign, open the console by pressing 'ctrl+backspace' (unless you've changed the keybinding), and type in 'addship' followed by your hull ID:


If you did everything correctly so far, it should print the above message and the ship will be added to your fleet. Go ahead and exit out of the console, press 'r' to open the refit screen, and take a moment to appreciate the beauty of your creation:


This also might be a good opportunity to activate devmode (type 'devmode' into the console and hit enter) and play around with it in the simulator, just to make sure it's all copacetic in the combat engine as well and adjust any stats you might need to -- devmode lets you reload data files such as ship stats from within the simulator by pressing F8, allowing you to test changes without having to exit and relaunch Starsector.

Once you've done that, we'll move on to the final steps: descriptions, variants, and campaign spawning implementation.

Descriptions Edit

You may have noticed when testing that your ship has the standard 'No description yet...' text string when you mouse over it. That's okay, we'll take care of that right now. First, create another folder:


Then, we're going to open the 'starsector-core/data/strings' folder, copy 'descriptions.csv', and paste it into ours. Open that file up and delete all the lines below the headers, just like you did with ship_data.csv. Next, we're going to add a line with the following information: 'id' needs to match the id of our ship in the .ship file and ship_data.csv, 'type' should (in this instance) be 'SHIP', and 'text1' will contain the actual description of our ship.

Note that while you can add new lines within the 'text1' cell using 'alt+enter', only the first line will be displayed in-game outside of the codex, so try to keep most of the immediately useful information there. The rest of the fields can remain empty for ships (though they are used for weapons and some other things).


Once you've done that, save the file, then open Starsector and look up your ship in the codex (or spawn it into the campaign again) to test and make sure it's reading correctly.


Looks like it is, so we're good to go! Time to move on to making a variant, and then making it spawn.

Loadout Variants Edit

First things first: Reopen the ship editor, press 'd' to load your ship, and then press '2' to go to variant mode. Press 't' to open the details pane, give your variant a descriptive name (the hull id should already be set, assuming you loaded your ship first), then press 'esc' to close the details pane and 'v' to save the variant. Make sure you're saving it in the 'mymod/data/variants' directory, which you'll have to create if it doesn't exist yet.

Note: If your ship won't load, press 'm' to load custom mod data and select your 'mymod' folder in the 'Starsector/mods/' directory, then press 'OK'.

Note: the standard convention for variant ids is 'modprefix_hullid_Variantname' -- you don't have to use this, but it will certainly make things more consistent. Note the capital letter at the start of the variant name in the id.


Once you've saved your variant, build it out with weapons and flux vents/capacitors using the hotkeys. You can also add hullmods here, or fighter wings if your ship is a carrier. Your ships current flux infrastructure and OP are displayed in the top left corner.

  • If it doesn't seem to be picking up the maximum OP correctly in the top left corner, exit the ship editor, check to make sure the id is set correctly in your ship_data.csv and that the file is saved in the right location, then re-open the ship editor and re-load your ship.
  • The 'Wings' setup (hotkey 'n') is currently busted, and won't let you exit the menu but will still let you save the variant from within it -- so do fighter wing setup last, if your ship is a carrier.


Now that looks like a fun and verisimilitudinous freight shuttle loadout! Press 'g' to setup your weapon groups before saving, then 'v' to save the variant, close the ship editor, and we're done!

Campaign Spawning Edit

Making our little Bastard spawn in the campaign is going to be fairly straightforward, but we will need a few more folders in our mod structure. Note that this is two new folders, a 'world' folder inside 'data', and then a 'factions' folder inside 'world'.


Go to the same folder path in 'starsector-core' (so, 'starsector-core/data/world/factions'), copy the 'default_ship_roles.json' file, and paste it into your folder. Open that up, and woah, that's a lot of text! Go ahead and delete everything but the categories you're actually using (you can copy in more categories from vanilla's default_ship_roles.json later, when you add more ships to your mod), then delete everything inside those categories -- what the categories do should be fairly self-explanatory. Some helpful tips though:

  • The number after the variant id in each list is the spawn weighting, i.e. how likely that variant is to spawn when the spawning faction 'knows' it and a ship of that category is needed. The default for vanilla Starsector is that each hull gets a total spawn weight of 10, divided equally between all of its variants, but you might want to give your hull a total spawn weight slightly below that if it's meant to be more rare, or adjust your spawn weight differently between variants if one is 'elite' or the like.
  • For testing purposes, you might want to set the spawn weight to something much higher, like 9999 -- just to make sure you don't have to fly around in-game forever before seeing one. Remember to set it back before releasing your mod, of course!

Once we're done, the file should look something like this:


Now we've got spawn weights set up, but the Bastard isn't quite fully implemented yet -- no faction knows how to build it, after all. In order to get that working, we're going to have to reopen our ship_data.csv file. Scroll over to the right to find the 'tags' column, and input some tags -- these determine who will 'know' the ship blueprint. Notes:

  • most tags ending in '_bp' are blueprint package tags -- adding a ship to these will make it 'known' by anyone who 'knows' that tag, and allow the player to learn it by finding the matching package blueprint.
  • the 'base_bp' tag is a special blueprint package tag -- adding a ship to this will make it known by all factions that know the 'base_bp' tag (that's all vanilla factions, and many mod factions too) as well as the player, from the very start of the game.
  • the 'rare_bp' tag works slightly differently -- adding a ship to this will allow the player to learn it by finding a blueprint for that specific ship and that ship alone. Generally speaking a ship should only be part of one blueprint tag -- either 'rare_bp' or a package blueprint.
  • tags corresponding to factions are faction tags -- adding a ship to these will make it 'known' by that faction specifically, without adding it to a package blueprint. Note that some factions have both a faction and a blueprint package tag -- i.e. 'pirate_bp' is a blueprint package tag, and 'pirates' is the faction tag for the pirate faction.

In this case, I want the Bastard to be fairly common among midline-capable factions so I'm adding it to the midline blueprint package tag, and besides that it seems like something that the Luddic Church would have access to despite not knowing the midline blueprint, so let's add it to their faction tag as well. Here's what this looks like all set up:


Save that file, and let's go test! Load up Starsector and start a new campaign, then open the console with 'ctrl+backspace' (again, unless you've changed the keybinding) and type 'findship' followed by your ship's hull id. Assuming you set the spawn weights and tags correctly, it should show up in a faction market or two -- but if it's not, try setting the spawn weights much higher (say, to 9999), starting a new campaign, and entering the console command again before you start troubleshooting.


If you see something like the above, then you're good to go! Congratulations -- you've made and implemented a new ship! We're all done!

Custom Weapon Edit

Custom Blueprint Edit

Custom Ship System Edit

Custom Hull Mod Edit

Custom Fighter Wing Edit

Custom Ship Skin Edit

Custom Faction Edit

Custom Market Edit

Custom Star System Edit

Lets start this with a link to a video using which I learned how to do this made by WadeStar. This video also has his mod frame for creating a star system. I do not know how to use java script so I will explain how to create your own star system for those like myself via copy/paste+logic)

First of all I have to point out that changing starsector core system scripts will not work. If you change them nothing will happen, I tried. To insert anything into them you need to use override commands and as I said I do not know how to use javascript. But they are still a good reference as to the structure of the star systems, if you find something you like in the core system you can go to (\Starsector\starsector-core\data\scripts\world)


and find the system you liked, then open it and look at its structure, there are a lot of features in core worlds that are not there in outer sector generator with custom rings/planet grafics and so on which you can try to copy into your own star system.

To create the star system you will need to use the star system mod frame mentioned above, it will have a lot of explanations in itself and the video will also explain a lot and in easy to understand form. Here I will explain the rest that I have struggled with when creating my own star system:


* First thing you see in the plugin file is this wall of text, please note that WadeStar's tutorial is for version 0.8 so I wasnt shure if all of things needed were there. I you can freely add lines your system lacks from starsector core as they are up to date. Or use one from my mod:


*If you change the name of the plugin file you have to change it here too(Here it is ColonyStarPlugin). If you dont the game will crash on starting up the game and log files wont tell you why.

*This here creates your star

	PlanetAPI star[star id, this is what planets orbit] = system.initStar(
		"laputa", [name of the star]
		"star_yellow", [type of the star]
		700, [size of the star in pixels]
		-7500, [x axis location in hyperspace]
		-4500, [y axis location in hyperspace]
		500); [radius corona extends from the edge of the star]

You can change [star] the id to anything you want but make shure that all other planets orbit what you changed it to.

*Down here is all you need to create a planet in your system

PlanetAPI stream = system.addPlanet("stream"[ID], star[What it orbits], "Stream"[Name you will see in game], "gas_giant"[Planet type], 230[Starring angle of the orbit], 350[Size in pixels, 5000[Orbit Radius], 150[Number of ingame days to complete orbit]);

You will need to remove everything in [ ] for it to work. All other lines of code are added on top of it. Without them it will be just a frame for a planet, unless you use fix all empty planets mod it wont have any market conditions like a lot of core worlds. It will also have a generic description and skin depending on its planet type.

*Down here is creating a market for any planet. It has to be there for terran worlds to be habitable and for gas giants to have dence atmosphere.

		MarketAPI stream_market = Global.getFactory().createMarket("stream_market", stream.getName(), 0);

What you have to note is that you have to make shure that you put correct ID's everythere or it will get messed up. For example if you put wrong id:


then when you try to colonise the planet, you will survey it just fine, you will see its awesome conditions with all ultrarich and all, you can salvage its vast ruins all good but when you try to colonise it SUDDENLY you get resourses for that taken but the colony wont be created.That is the same for everything here, you have to be very carefull or you will have a lot of crashes and bugs.

*Down here you can find all market conditions, although as I understood some are placeholders Alex plans to return back to the game later:

F:\Games\Starsector 0.9\Starsector\starsector-core\data\campaign\market_conditions

You can open it in something like wordpad too.

*This here is used to create nav_buoy/comm_relay/sensor_array/inactive_gate(note that for the gate faction has to be null)

	SectorEntityToken buoy = system.addCustomEntity("laputa_buoy"[id],
			 "Laputa Buoy",[name]
			 "nav_buoy",[token type]
	buoy.setCircularOrbitPointingDown(star, 40, 2000, 70);

List of all entities you can spawn this way:


*Also note that [StarSystemGenerator.addOrbitingEntities( ] will add not only planets but also rings, asteroid fields and so on so dont be afraid to set it to numbers of 10+ when using OLD seting due to most of it beying said rings and debris. YOUNG setting has much higher planet to debris ratio.

*Another note is that hyperspace storms wont be automaticly cleared from the location of the system. I am yet to find script lines to do that so you either dont mind that they ended up in hyper storm or look for suitable location without them.