Skip to main content



Everything you need to know about 1.17.1 modding with Forge.

For the 1.18 tutorial series go here

In these tutorials I assume that you already know Java. Note that you need to be familiar with more advanced concepts like generics and lambdas. Here are some useful links for learning Java:

Porting from 1.16.5 to 1.17.1

Two part tutorial explaining how to port a mod from 1.16.5 to 1.17.1:

Steps to port a mod from 1.16 to 1.17

Thanks to gigaherz for the original version of these steps:

  • Step 1: Make a copy of your 1.16 mod to a new folder or (alternatively) use GitHub to make a new branch and clone that
  • Step 2: Download the Forge MDK and copy over the gradle folder and gradlew scripts from there, nothing else
  • Step 3: Edit the build.gradle to use FG 5.1+:
classpath group: 'net.minecraftforge.gradle', name: 'ForgeGradle', version: '5.1.+', changing: true
  • Step 4: Open a cmd window or bash shell (for Linux) with java16 in the JAVA_HOME and PATH. Check with java -version that you really switched
  • Step 5: If your 1.16.5 mod is not using official mappings then run:
gradlew -PUPDATE_MAPPINGS=1.16.5 -PUPDATE_MAPPINGS_CHANNEL=official updatemappings
  • Step 6: Edit the build.gradle mappings line mappings channel: 'official', version: '1.16.5' [THIS IS IMPORTANT!!]
mappings channel: 'official', version: '1.16.5'
  • Step 7: Add the following line to your build.gradle:
apply from: ''
  • Step 8: Run the gradle command to update class names:
gradlew -PUPDATE_CLASSNAMES=true updateClassnames
  • Step 9: Change the build.gradle mappings line to mappings channel: 'official', version: '1.17.1':
mappings channel: 'official', version: '1.17.1'
  • Step 10: Change the sourceCompability = ... = '1.8' to '16'
  • Step 11: Change the forge dependency to minecraft net.minecraftforge:forge:1.17.1-37.1.1 [USE LATEST HERE, .1 WAS LATEST AT THE TIME OF WRITING]
minecraft 'net.minecraftforge:forge:1.17.1-37.1.1'
  • Step 12: Import into Intellij, changing Intellij's project SDK to java16, and making use the gradle JRE uses the project JDK too
  • Step 13: Run gradlew genIntellijRuns
  • Step 14+: Fix code and test

The New Tutorial Series

In this new series we start a new 1.17.1 tutorial from scratch. The previous porting tutorials focused on porting the existing old tutorial to 1.17.1. But if you are new and want to learn modding from scratch then this is the place to be

Episode One: Mod setup and first item

In this episode we show how to set up your project using IntelliJ. We start from the MDK and initialize everything, so you can start modding.

We also create the very first primitive item.

Concepts learned in this tutorial:

  • Events and the forge + mod buses
  • Setup events
  • Registration of items (and other things) and when this registration happens


Episode Two: expanding on our item

Here we fully flesh out the item we added in the previous tutorial:

  • A nice model (one that can change based on a property in the item)
  • Some functionality (a pickaxe with extra features)
  • A nice tooltip and a translatable name
  • A recipe

Concepts learned in this tutorial:

  • Difference between Item (singleton) and ItemStack (an actual item in the game)
  • Item properties
  • JSON models and recipes
  • Data generation (creating JSON files)
  • Minecraft API
  • Translatable messages
  • Client setup


Episode Three: making a power generator

In this episode we make a power generator (generating Forge Energy) that takes burnable items and converts them to energy:

  • The block can generate power (Forge Energy) from burnable items (coal, sticks, ...)
  • The generator has a distinct front face which will change if it is generating power
  • It will emit light when it is generating power
  • It has a gui

Concepts learned in this tutorial:

  • Blocks and BlockStates (with properties)
  • Block Entities
  • Capabilities (for power and items)
  • Generating Forge Energy
  • Data generation for loot, blockstate models and tags
  • Containers and Screens


Graph used in this tutorial:


Episode Four: making a machine that uses power

This is a small tutorial that expands on the previous one. In this episode we make a machine that can use the Forge Energy generated by the generator from episode 3.

Concepts learned in this tutorial:

  • Using Forge Energy
  • Render layers
  • Server -> Client communication for block entities


Episode Five: updating Forge, Parchment and Configuration

This tutorial starts by updating Forge and fixing the tool for a breaking change. We also start using Parchment to get better mappings for parameter names. Finally, we conclude by explaining how to add configuration to your mod.

Parchment: Parchment explanation

Concepts learned in this tutorial:

  • Updating Forge
  • Parchment
  • Three types of config (COMMON, SERVER, and CLIENT)
  • Registration BEFORE configuration!