An Introduction to Modding Minecraft

Introduction

The Minecraft modding community is thriving, having been around almost as long as the game itself - but to newcomers it can be a maze of outdated information, conflicting opinions and lacklustre documentation. This page aims to provide an overview of the modding scene in 2021, a guide to getting started, and some useful resources.

Official Modding API

For a long time, I put off any foray into Minecraft modding due to the promise that, one day, an official modding API would be released. While something akin to this has been released for Bedrock Edition, over time it has become increasingly clear that no such API will be released for Java Edition.

This seems to be due in part to the awesome efforts of the community with projects like Forge. Mojang even appears to officially endorse the modding scene. This level of collaboration between developers and modders is surprisingly rare in the gaming industry these days, and is one of the reasons that I have such respect for Mojang.

Know that @Mojang recognizes the awesome stuff the modding community has created and is actively making an effort to make modders lives easier going forward. They know the pains that each update to the game brings and they are working to lessen that pain.
— Direwolf20 (@Direwolf20) May 31, 2018

Why a Modding API?

The importance of a modding API may not be immediately obvious. If modders have direct access to the game's source code, why is a modding API necessary? Isn't it just an extra dependency to worry about? Doesn't it restrict creativity?

While it's true that modding APIs can be restrictive at times, they also bring a lot of benefits:

They provide a standardised means of achieving common goals (e.g. adding new blocks).
They allow mods to add features safely, without the risk of conflicts.
They can provide migration strategies to help mods remain compatible with new game updates.

What about Data Packs?

Support for Data Packs was added in 2018. Data Packs are very powerful and are fully compatible with vanilla Minecraft, as they use Command Block syntax to manipulate the game world.

Data packs can be used to override or add new advancements, dimensions, functions, loot tables, predicates, recipes, structures, tags, world generation settings, and biomes without any code modification.

While Data Packs serve as a legitimate substitute for many mods, their scope is nonetheless limited. For example, they cannot add new blocks or entity types, and they cannot add new functionality beyond the supported set of commands.

Mods can even add water to the Nether.

Enter Forge

Forge is basically a community-made substitute for the long-promised official modding API. It provides various mechanisms that allow modders to add their own functionality safely, without the risk of conflicts between mods. It is considered by many to be the "definitive" modding API, and it is certainly the most powerful.

Since the inception of mods, various modding APIs - or similar projects - have been developed. Here are some notable examples:

ModLoader was extremely popular in the early days of Minecraft modding, before eventually being discontinued in 2013.
Bukkit is an API used by CraftBukkit / Paper / Spigot servers that allows bespoke plugins to be installed, but being server-only modifications, they are limited in the scope of what they can do.
Sponge is another server-side plugin API which is compatible with both vanilla Minecraft and Forge.
Fabric is a mod loader that can apply patches to the game's code, and also provides an optional modding API. This is probably the main competitor to Forge.

While many of these have their place, the rest of this guide will focus on Forge.

Forge provides an abundance of hooks into the game logic that modders can use to inject custom functionality into Minecraft. For example, a mod can subscribe to events, like a block being broken, and override or extend their default behaviour.

The modder Draco18s paints a very positive picture of this mechanism when he describes his modding experience with Forge:

Modding Minecraft has seriously been one of the most enjoyable programming experiences I've ever had. Everything is laid out so well with incredibly intuitive and easy to use systems that let me hook into nearly everything.

I have been similarly impressed by the ease of mod-making. After more than fifteen years of evolution, the tools are extremely mature; in fact, there is an entire ecosystem of tools that work together in sophisticated build pipelines to make the whole process as seamless as possible for developers.

One of my first mods added a secret Cookie Dimension.

So, without further ado, let's get started.

Getting Started

Mod Setup

The Forge documentation is the best place to start, although it is not always especially thorough, and has been to known to become outdated (the prevailing attitude among the community seems to be that "the code is the only source of truth").

For me, creating a new Forge mod for development in Eclipse was as simple as downloading a handful of files and running:

./gradlew genEclipseRuns
./gradlew eclipse

It takes a little while, but these commands will create a simple example mod with all the required tools and dependencies, as well as an associated Eclipse project.

Testing Your Mod

During development, the mod can be launched by running:

./gradlew runClient

Publishing Your Mod

To build a mod for distribution, run:

./gradlew build

This creates a JAR file in build/libs, which can be placed in the mods folder of any Minecraft installation where Forge is installed.

Useful Resources

This guide provides a high-level overview of mod-making, but does not go into detail about the code. The resources below can help with the more nitty-gritty technical details.

That's All, Folks!

Hopefully you found this article useful or at least somewhat interesting. In the future I will probably write some more low-level guides to help with more specific modding tasks.

Published 2021/03/03

Last updated 2021/03/09