Tutorial: Developing Mods

Introduction

This tutorial will walk you through creating your first mod with Specter. While no prior programming experience is needed, basic technical skills are advised. If you need help, ask on Discord.

Specter can be used to mod programs written in languages like Java, Groovy, Scala, Kotlin, and Clojure that run on modern versions of the Java Virtual Machine (JVM). While possible to use any of those same languages to write your mod, this tutorial (and wiki as a whole) use Groovy for the sake of simplicity.

Although you can develop Groovy mods with just a text editor, proper tooling will benefit you in the long run, so the next section will walk you through setting up a development environment.

Setting up a Development Environment

If you don't have it yet, start by downloading the free community edition of IntelliJ IDEA (there's a paid version too, but you don't need it). Next, create a folder somewhere to hold your mod. We'll refer to this folder as <mods> going forward.

After that, download the latest release of Specter and Specter's IntelliJ integration, idea.groovy, and place them into <mods>. Now go to the launcher or terminal command used to run the program you want to modify and add -javaagent:/path/to/<mods>/Specter.jar=/path/to/<mods> to the JVM arguments. Next, run the target program to automatically create IntelliJ configuration files in <mods>. Once that's done, you can open the <mods> folder as an IntelliJ project.

Finally, we must manually change one thing in the project's settings to get proper editor support. With the project open, navigate to File > Project Settings > Project > SDK in IntelliJ and select a JVM version compatible with your target program (follow the menu prompts to add a new JDK if needed).

Now you're all set to beginning coding!

Writing Some Code

First, create a text file with the extension .groovy in <mods>; we'll call it example_mod.groovy, but you can pick a different name if you want (limit yourself to characters in a-zA-Z_ for now). Open it up, and add the following code.

println "Hello World"

Once that's done, press the green "▶️" button at the top of IntelliJ to run the target program (you may need to select a specific entry point from the dropdown if multiple exist; pick the most applicable looking one). If you check IntelliJ's console, you should see a line saying Hello World created by your mod.

Congratulations! You've made your first mod. What you do next is up to you. Look around the wiki to see how you can inject code in the target program, modify asset files, and more! If you're new to programming with Groovy, check out its documentation too!