Getting Started with Minecraft Modding

From time to time, I get inspired to go back to Minecraft and maybe start a "forever world" with lore and an expansive network of bases linked by roads or Nether portals or railways etc... However, I find the game to be a bit lonely - the NPCs are pretty limited. But I'm also not a social gamer, I just think it's fun when the gameplay has some interesting characters around to add some life. It would be cool to have some custom villagers living at my bases that do a bit more and maybe have a bit of personality.

I'm not much of Java programmer so I'd never seriously considered any Minecraft modding. However, we live in an age where learning a language and code base is greatly accelerated if you have access to an LLM so it became possible for me to upskill in this area.

Choosing a Framework

The two major players in modding seem to be Forge and Fabric. Forge is older and more complete. Fabric is light-weight and updates faster when new versions come out.

I chose the Fabric framework because I generally distrust frameworks that try to do too much for you. While they are more convenient to get started with, I find that once you are mature and experienced, they become a limitation and you find yourself having to mod the framework itself to get outside of the box it puts you in.

Having said that, I didn't actually try Forge so I'd be open to giving it a go some time to see what it's really like.

The downside of Fabric is that it's bare-bones - you have to figure out things and build infrastructure for yourself ... which actually suites me perfectly.

Installing Fabric

I run Linux for developing but I game on Windows. This is a bit inconvenient but I worked around it ok. The actual Fabric mod loader was pretty easy to install, just follow the instructions. Also I installed the Fabric API which is the base mod that provides all the hooks that your mod will use.

The dev environment was a little trickier. The first step was getting the right Java version. For Minecraft 26.1, I used Java version 25 (I can't remember how I landed on that version). I run Debian so the apt command was sudo apt install openjdk-25-jdk.

After this, I cloned the Fabric Example Mod , deleted the .git dir and reinitialised it as a new repo using git init. I probably should have used the template generator as per these Creating a Project instructions but I didn't see that until later on.

I didn't bother too much with the IDE stuff. I use VSCode but just stick to the file tree and text editing. I prefer to build and run other tools on the command line. Give the IDE stuff a look though - it will probably make it easier. Instructions are on that Creating a Project page that you should have just read. As I previously mentioned, I've made life hard for myself by developing on a headless Linux server and running desktop on Windows. It's probably just better to commit to one or the other instead of trying to play in both worlds.

The dev environment uses Gradle as the build system. It conveniently installs some dependencies as well. The Develop instructions have an example gradle.properties file which gets you started.

Before I could get too far, I wanted to have the Minecraft sources to look at as well as the Fabric API sources. The Fabric API is just a git clone: fabric-api. There is a Gradle command that actually decompiles Minecraft and produces the sources: ./gradlew genSources. This outputs two jar files deep in a subdirectory of the project. The idea is that the IDE should pick these up and know how to search them when you want to find sources. But because I'm difficult, I didn't want to set up my IDE for that. Instead: fd 26.2-sources.jar .gradle is the magic command to locate them. I then created a minecraft-sources dir and unpacked the jar files using the unzip command. Don't put that in your git repo btw, I don't think Microsoft would be cool with you distributing their code.

Build, Run, Debug and Learn Using an Agent

I was then able to build my first mod using ./gradlew build. I can't remember exactly what I did first, I think I worked through some of Creating Your First Item. The build command creates a .jar file in ./build/libs. I scripted a scp command to copy that onto my Windows PC at "$env:APPDATA\.minecraft\mods\" and fired up Minecraft to try it out. Note that it's handy to have VSCode open to "$env:APPDATA\.minecraft\logs\latest.log" so you can watch it crash.

At the start of this article, I mentioned using LLMs, this is the point at which I started leaning on one pretty heavily to figure out what to do. To start with, it's handy to drop crash dumps into the agent to diagnose what they mean and figure out what to fix. I also found the agent very good for explaining the Minecraft code base and the Fabric API so I could figure out what to do. Personally I wanted to learn this as much as I could so I would query the agent to locate files that dealt with interesting areas and give me code walkthroughs. I then wrote my best attempt at the mod and used the agent to fix my mistakes. I find this an effective way to learn.

In the next post, I'll talk about what my mod does and how it works.