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: Basic mod script debugging  (Read 4388 times)


  • Admiral
  • *****
  • Posts: 1183
    • View Profile
Basic mod script debugging
« on: May 03, 2014, 01:52:33 AM »

Hi Guys,

Thought I'd do an introduction to getting started debugging your Starsector scripts, and how to perform minor fixes to your code whilst Starsector is running:

EDIT: You will need to copy/paste this into either your Starsector.bat or vmparams (I cover it in the video)
 -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8888,suspend=n

Just as a reminder though, you cannot perform fixes to code that has not been compiled by you, that is to say loose scripts in your data folder cannot be updated on the fly. All the more reason to compile your code!

I only touched on how to get into debugging, and it was more on how to get started. There is great deal more to debugging than I covered in the video, I'd really suggest reading this NetBeans debugging Tutorial PowerPoint slide which covers the usage of the debugging controls and tools available:

« Last Edit: May 03, 2014, 01:59:40 AM by Debido »


  • Admiral
  • *****
  • Posts: 4506
    • View Profile
    • GitHub profile
Re: Basic mod script debugging
« Reply #1 on: April 30, 2020, 09:46:32 PM »

This got linked in a Discord pinned post recently, so here's a text version for anyone who just wants to know
"How do I modify my code in NetBeans without restarting Starsector"?

Using the debugger in NetBeans
(for Windows, should work similarly for Linux/Mac by editing different files)

Make a copy of starsector.bat and name it starsector_debug.bat. Replace its contents with, e.g.:

..\jre\bin\java.exe -Djava.library.path=native\windows -Xms4g -Xmx4g -Xss2048k -XX:MaxPermSize=128m -Dcom.fs.starfarer.settings.paths.logs=. -Dcom.fs.starfarer.settings.paths.saves=../saves -Dcom.fs.starfarer.settings.paths.screenshots=../screenshots -Dcom.fs.starfarer.settings.paths.mods=../mods -classpath janino.jar;commons-compiler.jar;commons-compiler-jdk.jar;starfarer.res.jar;starfarer.api.jar;starfarer_obf.jar;jogg-0.0.7.jar;jorbis-0.0.15.jar;json.jar;lwjgl.jar;lwjgl_util_applet.jar;jinput.jar;lwjgl_test.jar;log4j-1.2.9.jar;lwjgl_util.jar;fs.sound_obf.jar;fs.common_obf.jar;xstream-1.4.10.jar -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8888,suspend=n com.fs.starfarer.StarfarerLauncher
(RAM allocation here is 4G, change it if needed)

The relevant addition (compared to the unmodified .bat) is:
-Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8888,suspend=n
This allows the external debugger to attach to Starsector.

In NetBeans, after launching Starsector using your new .bat file, go to Debug -> Attach Debugger and enter the details in the window that pops up as shown below:

You should now have the NetBeans debugger attached to SS.
To make your modified code be reflected ingame, click the Apply Code Changes button at the top of the window:

You cannot do certain things like add/remove methods, or change their params or return types.
I've also found that changes to static final objects (as opposed to primitives) may fail to "take".
« Last Edit: May 05, 2023, 07:33:38 PM by Histidine »


  • Global Moderator
  • Admiral
  • *****
  • Posts: 6834
  • Harpoon Affectionado
    • View Profile
Re: Basic mod script debugging
« Reply #2 on: May 01, 2020, 09:47:11 AM »

Fantastic, thank you for taking the time to share this!

Moved to Modding Resources and added to the Modding Tools and Resources master page.