Fractal Softworks Forum

Please login or register.

Login with username, password and session length
Advanced search  

News:

Starsector 0.97a is out! (02/02/24); New blog post: Simulator Enhancements (03/13/24)

Author Topic: [Guide] How to set up IntelliJ IDEA for starsector modding (inc. jar files)  (Read 24425 times)

Darloth

  • Admiral
  • *****
  • Posts: 592
    • View Profile

See here for update notice!

Okay, so I finally got fed up of using a text editor, not having autocomplete, and most of all Janino not supporting generics.  To fix this, I looked through the available free Java IDEs, and found IntelliJ IDEA Community Edition.  It's free, has all of the features anyone modding will ever really need, and has what I think is a nice interface.

Given that, here's a tutorial for how to set it up so that you too can get autocomplete on starfarer scripts, along with how to make a jar file out of your mod's scripts and other code, so that you too can use generics (they're SO much easier).

First, you'll need to download it(Remember to pick the community edition - it's the free one. If you end up doing major java database development or groovy / android stuff then maybe the other one would be useful, but there's really nothing much in there that would be helpful for starsector.)(Starfarer!)

Once it's installed, you're also going to need the Java 7 SDK.  Getting this can be a little bit of a pain, as Oracle make you register an account to download old versions - you can do that somewhere around here, or find it elsewhere if you prefer.  Install it into some folder you can find again later.

Okay, so now you are ready to actually start IntelliJ IDEA for the first time.  Once it's loaded, create a new project.
You will get a screen with lots of options, titled: New Project.
Most of those options are pretty unimportant actually - there are three things you want to set here:
  • First, make sure it says Java Module from the list of types on the left. 
  • Second, set the name and location to whatever you want (Note: do NOT set the location to anywhere in your starsector folder - you'll regret that later, but we'll get to that.)
  • Third, you need to set the Project SDK to the Java 7 SDK you downloaded and installed earlier, and you'll need to click the New button, select JDK, and then point it at the right folder to do this. 
  • You can safely ignore everything in More Settings, just leave those as the defaults.
Press Next, and it will ask you to select extra technologies - usually only Groovy will be an option, and we won't be using that, so just press Finish.

You should end up on the main screen, a big grey background on the right, and then a foldertree tray window at the left, with one folder named whatever you named your project, and also External Libraries as a little bookshelf icon.  Open up the folder for your project, and have a look around. The src folder is where you'll put all your source files - most likely you'll make a data.scripts subfolder under this. Leave the .idea folder and the .iml file alone as those are editor-specific project settings you shouldn't need to mess with.

Next we're going to add starsector's own API as another library to draw from (you'd do the same for LazyLib or other libraries, if you want those):
  • Go up to the File menu and select Project Structure.
  • From the tab selector on the left of this new window, pick Libraries.
  • Above the tray just to the right of that, click the green Plus symbol.
  • Pick Java as the type(I don't even know what Maven is, some sort of nugetlike thing?), and you'll get a directory selector tree.  Navigate to your starsector installation, go into starsector-core, and lots of jars will be displayed. You want to ctrl-click multiselect starfarer.api.jar, starfarer.api.zip, lwjgl.jar and lwjgl_util.jar.  With those selected press OK.
  • Press ok again to add it to the only module you have, named whatever you picked.
You should now have some stuff on the right of this screen, three classes and one source.  If the name hasn't been automatically set to starfarer.api at the top right, do that now too, and press Apply.

Next we want a jar file, right? For reasons unknown to me (but probably quite sensible early on) Java calls these artifacts, so go to the artifacts tab on this same menu (see, that's why you clicked Apply and not OK).  Click the green plus on this one again, pick Jar then Empty, and you will get new details on the right:
  • From the Available Elements window, doubleclick the one that has your module's name followed by 'compile output'.
  • Right click on the jar file (in the left window, probably called unnamed.jar at the moment) and select Create Directory.  Call it "source".
  • Right click on that directory and Add Copy Of -> Directory Content.  Select the src directory from the popup.
  • Change the artifact name to something you want - probably matching the module name.
  • Change the output directory at the top of this screen to be wherever your starfarer mod folder is - basically, where you actually want your jar to go.
  • Build on make is also a good idea - this should make the jar file build every time you compile your project.  It's not essential, you can leave it turned off and do it by hand in the menu if you'd prefer it.

We're nearly done now!
Right click on the src folder and select new->Java class. Call it, I dunno, "data.scripts.YourModPlugin" or something.  Note that you can include the path here, and it'll make the necessary folders!

In your new file, just after it says "public class YourModPlugin" type "extends BaseMo" and notice that the autocomplete has (if everything went well!) picked up the starfarer API and can happily tab-complete this to BaseModPlugin. Even better, IntelliJ will put in the appropriate import for you, isn't that awesome? (I think it is!)

Now you can do stuff like "List<StarSystemAPI> places = Global.getSector().getStarSystems();", with none of that pesky casting of object types.  If anything shows up red, click on it to put the caret there, and a lightbulb will probably pop up that you can click on for an explanation and hopefully a suggestion of how to fix it - IntelliJ will often have a solution or a thing that will change it for you to be correct, and I believe alt+enter is the shortcut to get that menu or do that thing if you don't want to use the mouse.

That should be you set, just compile things from the Build menu or I think it's F7 by default, and assuming you checked Build on Make earlier, the jar file should be where you want it. If not, or if you want to do it yourself, there's a Build Artifacts command in the build menu.

There are other tutorials about how to actually USE the jar, but mostly, just point your mod at it with mod_info.json's jars option and everything should work as you expect. 

Two small notes: if you have a class at src/data.scripts.YourModPlugin, because src is the root source folder, you shouldn't include it in paths: your modPlugin line in the mod_info.json should actually read: "modPlugin":"data.scripts.YourModPlugin",

Second thing: By default, IntelliJ clears out the entire output folder whenever you compile.  This is why you do NOT want to point it at your starfarer mods folder, you'll lose other stuff like resources.csv.  It doesn't clear stuff where it puts the .jar file, just wherever you're actually compiling too. If you left it as the default, and made sure not to put your project under your starfarer folder, all will be well.

(If anyone really needs screenshots, let me know - but they'll just be of windows and menus, and since there's a limit of 4 per post, I want to see where people get stuck, IF they get stuck, before taking any.  Hope that helps, and happy modding!)

Edit: Just in case it might help, I attached the entire project I created as I was writing this tutorial - you should be able to load it and poke around in settings / structure to see how it's set up. One caveat is I didn't actually set my jar to be written to my starfarer folder, so you will have to do that manually if you use the attachment.


[attachment deleted by admin]
« Last Edit: November 12, 2023, 08:16:42 AM by SirHartley »
Logged

Okim

  • Admiral
  • *****
  • Posts: 2161
    • View Profile
    • Okim`s Modelling stuff
Re: [Guide] How to set up IntelliJ IDEA for starsector modding (inc. jar files)
« Reply #1 on: September 19, 2013, 12:07:13 PM »

Finally got my hands on that program. Created a jar with the help of your tutorial.

Testing it now with Uomoz`s angry stations dialog plug-in...

EDITED:

...and its being initialised, but does not work. Hmm...
« Last Edit: September 19, 2013, 12:12:51 PM by Okim »
Logged

Darloth

  • Admiral
  • *****
  • Posts: 592
    • View Profile

Apologies for dragging this up the board, but can some-mod move it to Modding Resources please? It had become lost in the mists of time, but I still think it's worthwhile for anyone who wants to use IntelliJ.

If you disagree, I won't bump it again.
Logged

LazyWizard

  • Global Moderator
  • Admiral
  • *****
  • Posts: 1363
    • View Profile
    • GitHub Profile

Done. I added it to the pinned resource thread as well. :)
« Last Edit: August 27, 2014, 01:35:46 PM by LazyWizard »
Logged

Dark.Revenant

  • Admiral
  • *****
  • Posts: 2806
    • View Profile
    • Sc2Mafia

Might want to edit the post slightly to at least say Java 7, since Java 6 is completely deprecated for Starsector.
Logged

Darloth

  • Admiral
  • *****
  • Posts: 592
    • View Profile

Oops - yep. Thanks.
« Last Edit: August 28, 2014, 01:15:49 PM by Darloth »
Logged

Wispborne

  • Captain
  • ****
  • Posts: 400
  • Discord: wispborne
    • View Profile

This guide hasn't been touched since 2014, but is the 5th result on Google for me for "starsector intellij" and people are still finding and using it, so I'd like to make a few clarifications.

There are newer IntelliJ guides. This one should be the most up-to-date, being a wiki that anybody can update: https://starsector.fandom.com/wiki/IntelliJ_IDEA_Setup.

However, if you do want to use this one, I have a few thoughts/suggestions:


- Please DO NOT use "data.scripts" for your source files. Use something unique, such as "yourName.yourMod", e.g. "wisp.overhaulmod".
This will help a lot with making sure that bugs find their way to the correct mod author, as your name and mod will show up in the crash's stacktrace.
It is frustrating for tech support to figure out which one of 50 different mods caused a crash because they all used "data.scripts" and a two-letter acronym on their class names.


- When adding Starsector's dependencies to your project, the line "You want to ctrl-click multiselect starfarer.api.jar, starfarer.api.zip, lwjgl.jar and lwjgl_util.jar."
You probably also want to add most of the other jars in that folder, especially json.jar, log4j, and maybe starfarer_obf.jar and xstream as well.


- The way this guide sets up your mod, it splits things into two locations.
  - Your mod (images, sounds, .json files, .csv files, etc) will be in your Starsector mods folder.
  - Your source code (IntelliJ project) will be outside of there, and will compile a .jar that gets placed in your main mod's folder.

  That's fine, and makes distributing your mod easier by keeping the mod folder clean of IntelliJ files, but it does mean that you won't be using IntelliJ to view and edit your non-code mod files.
  The guide does include putting your source code right inside your jar (which is really nice!), so it will get saved if you only back up/commit your main mod folder and not the IntelliJ project.


Other than my first item (please stop using data.scripts!), this guide holds up really well over the years.
Logged
Mod: Persean Chronicles | Mod Manager: SMOL | Tool: VRAM Estimator | Tool: Forum+Discord Mod Database | If I'm inactive for 3 months, anyone can use any of my work for anything (except selling it or its derivatives).