[2012-11-28] Writing Minecraft mods

I've been playing around lately with writing mods for Minecraft, most importantly this one mod called LiquidUU. It's an interesting experience.

Before I really even started doing this, I commented somewhere something along the lines of "writing mods is not really all that different from writing programs in general, except that most of the heavy lifting has already been done for you". This is deceptively true, in that it's not really the full story.

You see, most of the heavy lifting has been done for you, so now it's your job to figure out where it is and how to make use of it instead of re-implementing something that's already available. Specifically, for Minecraft, especially with Forge, you get a lot of autogenerated javadoc which, supplemented with reading the original code, will let you do just about anything you want -- as long as you spend the time to dig through all of it to find how it normally works.

If I have any complaint about Minecraft modding, it is simply that documentation is sparse, and example code is fairly rare and possibly outdated, which makes getting started fairly tricky.

For instance, if you look at where I found the only documentation of @NetworkMod.versionBounds, it tells you "[if] you put [4.0] as the version bounds, The server will take any clients that have the first two numbers, 4.0, The rest of the numbers don't matter." Sounds good, right? Except, it doesn't work that way (at least, not anymore, if it ever did). Trying to use it that way will result in Forge telling you "The mod LiquidUU does not accept its own version (0.7.1)! This is likely a major bug!".

Okay, okay, maybe a look at the javadoc will help. What's it say about @NetworkMod.versionBounds)? "An optional range check for client to server communication version compatibility". Hmm. Well, that's "useful" information, it does what it sounds like it's doing... What does this range check look like, though? Does looking at the code help? No... not there, at least.

Eventually, if you look around enough, you arrive at cpw.mods.fml.common.versioning.VersionParser, which tells you what you really needed to know, which is that "Bounded version specifications are defined [at] http://maven.apache.org/plugins/maven-enforcer-plugin/rules/versionRanges.html". Which tells us that if we want to accept 0.7.anything, but not 0.8 or greater, we should be passing it "[0.7,0.8)". That took me a good 30 minutes or so of searching at one point.

So, going back to my initial statement: "writing mods is not really all that different from writing programs in general, except that most of the heavy lifting has already been done for you", it's still true, but if you're not a programmer, you won't know the shadings of it. That sometimes the language you're writing in has such terrible documentation that figuring out how to print a line can be a 30-minute challenge, maybe. That other times you have this neat documentation package that tells you everything, including some of the rough edges you may run into. Examples of both are left to the reader's determination.

In the case of Minecraft, writing mods is an interesting, challenging, and I dare say, fun (both in the literal and the Dwarf Fortress sense) exercise in digging fairly deep into decompiled code with variable names like "var11" and "var13" and "par2" to find that one nugget of gold that will do exactly what you wanted to do, and you know it's possible because {some other mod} or {some vanilla block} does something like it. It's a challenge, and occasionally a long slog, but it's also tremendously satisfying to see that your machine is now using the right amounts of its resources, and it's displaying all the right stuff, and when you place it in the world it's facing away from you... truly, an experience worth having.

Published 2012-11-28, 01:45 UTC +0200.