Minecraft Modding Primer

Note: This primer assumes no prior experience modding Minecraft. However, you will need to have a firm grasp on programming in Java to work with Minecraft (see the Prerequisites section). If you are coming to Fabric from another modloader, like Forge, the introduction will probably be more at your level.

This document is meant to serve as an introduction to modding for anyone who doesn't know a BlockPos from a BlockState. If you have experience with datapacks and want to take your skills to the next level, or you are learning to program in object-oriented languages and want a fun project to help you along, this is the document for you. First, let's start with what you need to know beforehand:

• You must understand the basics of coding. If you have never touched code before, you must learn how to code first. “The basics” here means having a firm grasp on variables, functions, classes and methods, and object-oriented programming concepts like inheritance, polymorphism, and object casting. Your search engine is your friend!
• You should have some experience in a programming language like Java or C/C++/C#. Java's syntax is relatively simple to pick up for someone coming from the C family.
• Familiarity with Java's syntax for lambda methods, generics (you should know what these are), and syntactic sugar like the ternary operator will be very helpful– but this is something that a quick learner can pick up along the way.
• You must know how to use the Internet to find answers to questions, and etiquette for asking for help on forums.

Modding is the process of either adding to or modifying a program's source code; in this case, the program is Minecraft. All mods you will ever make will do at least one of those.

Fabric is a set of tools that makes it easy to mod Minecraft. These tools are:

• the Fabric Loader– a framework for loading modded code into Java-based games like Minecraft.
• Fabric Loom, which is a build system designed for modding with Fabric.
• Fabric's language modules that allow you to use other JVM languages like Kotlin or Scala to program your mods. Note: it is recommended that beginners start with Java, since it's what Minecraft is written in, and is the easiest language to find help for.
• the Fabric API– a set of tools that make adding or modifying certain common Minecraft features easier.
• the Fabric Installer– a tool that installs the Fabric Loader on an end user's Minecraft installation.

To more easily understand what is going on in Minecraft's code, when you mod with Fabric, you will also have access to Minecraft's source code. Since Java is a compiled language, we need to decompile the code before it can be read. This turns it from Java bytecode into human-readable Java source code. However, to stop reverse engineering, Mojang distributes Minecraft in obfuscated format. This means that all the classes, methods, and fields in the code have randomized names. You can see this for yourself by opening a Minecraft .jar file in a zip extractor tool– all the files have names like abc.class. And what's worse, there's no guarantee that an object will have the same name between two versions– it could be called abc in one version, and abd in the next. This would make modding really, really hard, because without names, it's hard to tell what different variables do. To fix this, Fabric uses a set of mapping tools to give everything a human-readable name.¹⁾

• the intermediary mapper is a program that gives every single object in Minecraft's code a name like “field_10832”, or “method_12991()”. Critically, this program always names each object the same thing. So a method that does not change between versions will always have the same intermediary name.
• yarn is the final step in the deobfuscation process. Yarn is a libre, open-source community-driven library of names for all the methods and classes in Minecraft. When you look at the source code for Minecraft, any class, variable, or method that has a name describing what is does was written with Yarn. Someone in the community analyzed and decided to name it that. Every time a new update or snapshot comes out, the community gets to work combing through the code to see what new objects need names.

Not everything in the Minecraft codebase is mapped with Yarn– sometimes you will see variables that still have intermediary names. If you figure out what they do, you can contribute a name for Yarn.²⁾ Check out the mappings page for more information about using and contributing mappings.

Minecraft: Java Edition is a huge project, with years and years of code built on top of each other. It can seem chaotic (because it is), but there are a few key concepts that are (mostly) consistent across the board.

Most “features” (things you might want to add) in the game (blocks, items, screens, entities, chunk generators, etc.) are loaded into Registries when the game is loaded. For example, each Item has a single static instance that is initialized when the game starts, and is put into the item registry. The game uses that instance to determine the properties that ItemStacks (the memory representation of the items you can hold in your inventory) of that item have. If you add something to the game, you probably have to register it. There are exceptions to this rule, however: some features in Minecraft are data-driven, meaning that they can be defined purely in terms of data (as opposed to code). If you've ever wondered why datapacks can add some things but not others, this is why: datapacks can only add data-driven content. Some examples of data-driven content in Minecraft include biomes, textures, *some* chunk generators, and crafting recipes. When a world with a datapack is loaded, the game automatically adds these features to a special transient registry only used while that world is loaded. If you've developed datapacks before, you can integrate datapacks into your mods very easily, which makes some content easier to create. You can even add your own data-drivable content that other people can make datapacks for using Codecs.

Minecraft's processing is split between two threads, commonly called “sides”: the server side, and the client side. The client always runs on a player's computer and handles rendering and input. The server can run either on its own as a dedicated server (what you probably think of as a “Minecraft server”), or, in singleplayer, on the player's computer along with the client as an integrated server. The server handles everything the client doesn't– inventories, the world itself, et cetera. The client and server must agree on certain things: what blocks are in the world, what is inside chests, player position, etc. Since these are handled by the server, it dictates to the client what these values should be, and the client displays them to the person playing the game. Anything handled by the client does not have to be told to the server at all– this includes what blocks and entities look like (resource packs), and how to draw the world (shaders). This is the distinction between clientside mods (like shaders), serverside mods (like those that run minigames), and both-sided mods (those that add things like machines or new blocks and items). It is important to not call client-only code (i.e., relating to rendering) on the server, and server-only code on the client. This is the purpose of the ubiquitous world.isClient() checks that you often see in Minecraft modding.

Once you've achieved the prerequisites and have read this document, it's time to get started! Check out the introduction to learn about the ins and outs of Fabric as a platform, read the setup document to set up an IDE to mod Minecraft, and then head to the items tutorial to add your first item!