Getting started with mod programming

From Starsector Wiki
Jump to navigation Jump to search

Any complex mod will require some degree of custom logic, which is done using programming (also called scripting). Custom logic is written in Java or Kotlin (what is this?) as part of your mod and then gets run by the game.

Starsector uses Java 7 (also known as 1.7), released in 2011, and all mod source code must target Java 7.

What is programming?

Programming is how we tell the game how to do something that it doesn't already know how to do.

For example, if we want to move the planet Jangala, we could write some code: jangala.setLocation(0f, 0f); and this would move the planet to the center of Corvus.

A non-exhaustive list of tasks that require programming are:

  • Adding a new star system (possible through .csv files, but limited)
  • Custom weapon logic
  • Most bar events
  • New ship systems
  • New abilities
  • New hullmods


Learning to Program


Compiled .jar vs Janino

Code, aka source code in a .java file, has to be understood by the computer to work. There are generally two different approaches.

Compiled code

Compiled code is converted from the source code, like Java, to something easier for a computer to understand (but very difficult for a human to). This process is called compiling or, sometimes, building. The compiler is also able to make various optimizations to code when it compiles it. For Java and Kotlin code, the compiler creates a .jar file, which is a compressed folder of .class files (a .class file is a compiled Java/Kotlin file).

Compiled code is the way that Java/Kotlin are generally used, and is the most supported and recommended method.

Janino

Janino is a special tool used by Starsector that can run Java source code without needing it to be compiled into a .jar file ahead of time. This is simple and convenient, as the file can be edited and then the game run without ever needing to set up or run a compiler.

However, Janino has some limitations, covered here: https://janino-compiler.github.io/janino/#limitations. There have been a few other random-seeming issues as well, where the same code may not work uncompiled using Janino, but does work once compiled.

Janino is not recommended. Despite taking longer to set up, an IDE that compiles your code will save time in the long run by catching errors earlier, giving better error messages, allowing debugging, and a large number of other benefits.

Janino is... it's not quite deprecated, as far as its place in the Starsector code - that is, there's no danger of me wanting to remove it - but it's about as close as can be to that otherwise.

- Alex


Recap

  • .java is a text file with Java code that a programmer edits. This is the one you want to change. The location of these varies from mod to mod (and some mods don't include it), but it's often in a folder or .zip file called src.
  • .class is a compiled .java file and is only for the computer to read.
  • .jar is a fancy .zip full of .class files. It generally contains all of the logic for a mod and is only meant for the computer to read.


Getting Set Up (IDEs)

Just as professional writers use tools like Microsoft Word and professional artists use tools like Adobe Photoshop, so too are there specialized programs for writing code. These are called IDEs, or Integrated Development Environments.

Do not use Notepad to edit code.

Why use an IDE?

An IDE has many advantages over a simple text editor, including:

  • Highlights issues that will prevent your code from running/compiling.
  • Automatically adds import statements.
  • Auto-complete of class/method names, including listing all methods for a vanilla class.
  • One click to run the game with your mod.
  • The ability to pause the game and see what's happening in your code (debugging).


Choosing an IDE

Biased IDE Comparison by Wisp
IntelliJ Netbeans VS Code Eclipse Notepad
Price Free (Community Edition) Free Free Free Free
OS Windows/Linux/MacOS Windows/Linux/MacOS Windows/Linux/MacOS Windows/Linux/MacOS Windows
Java/Kotlin Java/Kotlin Java Java/Kotlin Java Text
Popularity 5/5 4/5 5/5 3/5 3/5
Power 5/5 4/5 2.5/5 4/5 0/5
Ease of Use 5/5 5/5 4/5 3/5 0/5
Download https://www.jetbrains.com/idea/download (choose Community Edition) https://netbeans.apache.org/download/index.html https://code.visualstudio.com/download https://www.eclipse.org/downloads/

Using a good text editor is also possible, such as Notepad++, but it will not have as much out-of-the-box support as a full Java-focused IDE.


Setting up an IDE

IntelliJ

NetBeans

VS Code

Eclipse


Mod Templates

While IDE setup guides may step through setting up a mod, it's also possible to start using a mod template.

  • Mod Template for Java by Wisp
    • This template uses standard IntelliJ configuration; it is very similar to the IntelliJ setup guide, but has most configuration already done, without needing to do it by hand.
    • Only for IntelliJ.
    • Follow the readme on the GitHub page for setup instructions.
    • Provides full in-editor documentation for Starsector API.
    • One-click Run Configuration for IntelliJ to compile and start Starsector with debugging.
  • Advanced Mod Template for Java and/or Kotlin by Wisp
    • Caution: This template goes far off the beaten path for IntelliJ setup and if something goes wrong, you and others will probably not know how to fix it.
    • Video setup tutorial: https://youtu.be/q63p67f-F8k
    • Gradle build system, works with any IDE.
    • Provides full in-editor documentation for Starsector API.
    • Optionally creates & updates mod_info.json and Version Checker files automatically based on Gradle script variables.
    • Includes GitHub Actions setup to auto-build a versioned zip in GitHub Releases when a git tag is pushed.
    • One-click Run Configuration for IntelliJ to compile and start Starsector with debugging.


Java or Kotlin

Java will be the better choice for the vast majority of people.

Pick Java if:

  • You are new to programming or already comfortable with Java
  • You want coding help from the community
  • You want the simplest, easiest way forward
  • You want others to be able to read and contribute to your code

Pick Kotlin if:

  • You are familiar with C# or other similarly modern languages and cannot live on Java 7's features, and
  • You will get by without much coding help from others (most modders will not fully understand Kotlin's syntax), and
  • You are ok with relying on LazyLib (which will provide the Kotlin Runtime)
  • Note: Kotlin is dropping support for Java 7 in a future version (Kotlin 1.6 or later). This means that Kotlin users will be forced to stay on the final version of Kotlin with support for Java 7.

Kotlin learning resource:

  • Kotlin Koans: by the devs of Kotlin, this tutorial uses your existing programming knowledge to introduce the Kotlin syntax


FAQ

  • How do I make a .jar?
  • I edited a mod's .java files, but the changes aren't showing up in the game!?
    • You need to compile the .java files by making a .jar. See rest of FAQ.
Retrieved from "https://starsector.wiki.gg/wiki/Getting_started_with_mod_programming?oldid=24259"