Rescomp Extensions for SGDK with Maven

SGDK is an amazing framework for building Sega Genesis games. Among its features is the tool rescomp, which compiles resources like images and audio for use inside your game. The rescomp tool offers a path for extension. I’m currently using a rescomp extension to import my collision map from a csv file in ldtk’s super simple export. This guide should allow you to more easily write extensions for your specialized resources as well.

I’m building my rescomp extension with Maven because it alleviates the burden of having to manually manage my classpath. This unlocks my ability to use basically any package in the Java ecosystem when processing new resources for integration into a game.

This guide is pretty barebones, but I really wanted to get this basic overview out while it’s fresh in my mind. Hopefully, at some point, I’ll have a bigger project with a better practical example of how the rescomp extension feature can be used. For now, you can use my rescomp-ext-sample project to get a slightly more complete picture of the whole process.

Prerequisities

Install Java, Maven, SGDK 2.10 or above¹, and an SGDK project you’re working on.

I use VS Code right now, but you can use whatever you want.

For this tutorial I’m using powershell. So run all of the commands there, or adjust them for your terminal of choice.

Set the environment variable GDK to point to your SGDK install - this is also useful if you want to use the Genesis Code VS Code extension.

Don’t forget to check in any work in progress in your favorite version control system in case any of this breaks something you were working on.

A quick aside about Maven

If you’ve never used Java and Maven before I recommend looking up some tutorials.

Don’t get frustrated, maven sucks. In 15 years of professional development I have never once had someone else’s maven project run correctly on the first try. I consider that to be maven’s fault. Good luck! The fact is, once you get past that, having a package manager opens up enormous possibilities, and will save you time over maintaining your classpath manually.

Step 1: Install rescomp in your local maven repo

In the future, rescomp may be available in the public Maven Repository, for now though, you’ll need to install it locally. You can find an explanation of local installs here.

In powershell run the following command:

mvn install:install-file -Dfile=%GDK%/bin/rescomp.jar -DgroupId=sgdk -DartifactId=rescomp -Dversion=3.95 -Dpackaging=jar -DgeneratePom=true

Adjust the version to match your version of SGDK’s rescomp, which you can find at %GDK%/bin/rescomp.txt

You will need to redo this whenever you upgrade SGDK. Keeping old versions separate will allow you to switch between old projects and new ones with less difficulty.

Step 2: Create a basic maven project

Currently rescomp only accepts a single extension using a class loader for a jar named rescomp_ext.jar. If you want to write a rescomp extension for multiple projects, I recommend writing a separate maven package and importing it into each project’s rescomp_ext pom.

I used the default archetype from Maven in 5 Minutes but this could definitely be cleaned up.

In powershell:

cd <path to your project>/res
mvn archetype:generate "-DgroupId=%DOMAIN%" "-DartifactId=rescomp_ext" "-DarchetypeArtifactId=maven-archetype-quickstart" "-DarchetypeVersion=1.5" "-DinteractiveMode=false"

Replace %DOMAIN% with your own domain (in reverse order) if you have one, or just make one up. So for me I put com.radicaledward101. The artifactId must remain rescomp_ext.

Delete the App.java and AppTest.java files that get generated as we won’t need them.

I recommend you check these changes into version control at this step, and after each subsequent one. That way, if something breaks in the subsequent steps, you can backtrack. This will also let you diff your changes and compare against each step to make sure you’ve got everything!

Step 3: pom.xml modifications

In pom.xml make the following changes. A completed pom.xml is available here.

Add rescomp to the dependencies:

1<dependencies>
2    ...
3    <dependency>
4        <groupId>sgdk</groupId>
5        <artifactId>rescomp</artifactId>
6        <version>3.95</version>
7        <scope>provided</scope>
8    </dependency>
9</dependencies>

Put it in the regular dependencies not dependencyManagement. The provided scope is needed to prevent duplicating the rescomp classes.

While we’re in here, we should update to a newer version of Java. Find the existing maven.compiler.release tag and adjust it (confirm that this matches the version of Java you have installed):

<maven.compiler.release>23</maven.compiler.release>

Now let’s add the <build> config inside the main <project> tag with the maven-assembly-plugin so we can build our jar:

 1<project>
 2    ...
 3    <build>
 4        <finalName>rescomp_ext</finalName>
 5        <plugins>
 6            <plugin>
 7                <groupId>org.apache.maven.plugins</groupId>
 8                <artifactId>maven-assembly-plugin</artifactId>
 9                <executions>
10                    <execution>
11                    <id>create-my-bundle</id>
12                    <phase>package</phase>
13                    <goals>
14                        <goal>single</goal>
15                    </goals>
16                    <configuration>
17                        <descriptorRefs>
18                            <descriptorRef>jar-with-dependencies</descriptorRef>
19                        </descriptorRefs>
20                        <appendAssemblyId>false</appendAssemblyId>
21                        <outputDirectory>..</outputDirectory>
22                    </configuration>
23                    </execution>
24                </executions>
25            </plugin>
26        </plugins>
27        ...
28    </build>
29</project>

This should create the jar one level up, in the res folder, which is where SGDK expects it (at least when using the Genesis Code VS Code extension build commands).

Step 4: Add a new Resource and Processor

Extend Processor and Resource to add a new resource type. These will be unique to your needs. You can use the Resources and Processors in rescomp itself as examples. I also have examples available for a CSV Resource and a CSV Processor.

At this stage you may need to know some minimal amount of 68k assembly to know what output to provide, but you can also make use of Bin and SObject to get some of that for free.

Step 5: Build the jar

From the res/rescomp_ext folder run the command

mvn clean install

If all goes well you should now have the file res/rescomp_ext.jar in your project.

Step 6: Add a resource with the new type

In your resources.res file.

For me that looks like this .res file sample

CSV collisionMap "collisionMap.csv"

Step 7: Test

Run the following

java -jar %GDK%/bin/rescomp.jar res/resources.res res/resources.s

You can read res/resources.s assembly with any text editor to ensure that your new resource is being imported correctly.

Delete res/resources.s when you are done testing. Otherwise it will interfere with your build.

Step 8: Declare the C type for your new resource

Next you’ll need to declare any custom types for the data you’re outputting. This will probably come in the form of structs for complex data, or in my case an array of numbers. I recommend writing a rescomp_ext.h for this purpose. I have an example here.

Step 9: Start using your newly imported data

And that should be it! If everything went well you should have a new rescomp extension and access to your custom data inside your game!