Working sample code for the basic concepts in Minecraft and Forge.


MinecraftByExample [1.16.4]

The purpose of MinecraftByExample is to give simple working examples of the important concepts in Minecraft and Forge. If you're anything like me, a good code example is worth several screens of waffling explanation, and can very quickly explain the key concepts. I also find it much easier to adapt and debug something that already works, than to have to synthesize something from scratch and spend hours trying to discover the missing bit of information I didn't know about.

I've tried to keep the code simple and obvious and to resist the urge to be clever. The examples might not be the most efficient or succinct implementation, I've deliberately left the optimization to you.

Each example is split up to be totally independent of all the others. The only part of the code which is common to more than one example is the MinecraftByExample class.

If you want more information and explanatory text about the concepts, the following links might be useful:

For earlier versions, see the relevant GitHub branch:

If you are updating from previous forge versions, you will probably find this link and this link very helpful. For better or for worse, MCP decided to rename a very large number of classes (eg all Blocks Blockxxx --> xxxxBlock, etc) so this might save you a stack of time. If you use IntelliJ, you might find these xml mapping files useful too

List of examples

See here for pictures of what each example looks like in-game.


  • MBE01 - a simple cube
  • MBE02 - a block with a more complicated shape
  • MBE03 - two types of blocks which vary their appearance / shape:
    a block (coloured signpost) with multiple variants- four colours, can be placed facing in four directions
    a block (3D Web) with multiple parts (multipart) similar to a vanilla fence.
  • MBE04 - dynamically created block models
    a camouflage ("secret door") block which dynamically changes its appearance to match adjacent blocks - uses IBlockModel.getQuads(), ModelBakeEvent, IForgeBakedModel and IModelData
    an "altimeter" block which shows the block altitude (y coordinate) on the side in digital display - as camouflage block but uses programmatic generation of quads
  • MBE05 - multilayer block (lantern block with transparent glass) with animated flame texture
  • MBE06 - several different types of block which use redstone
  • MBE08 - how to add a creative tab for organising your custom blocks / items


  • MBE10 - a simple item
  • MBE11 - an item with multiple variants - rendered using multiple models and multiple layers
  • MBE12 - an item that stores extra information in NBT, also illustrates the "in use" animation similar to drawing a bow
  • MBE15 - a chessboard item with 1 - 64 pieces; uses ItemOverrideList.getModelWithOverrides(), IBlockModel.getQuads() and onModelBakeEvent()


  • MBE20 - using a tile entity to store information about a block - also shows examples of using NBT storage
  • MBE21 - using the TileEntityRenderer to render unusual shapes or animations

Containers (Inventories)

  • MBE30 - a simple container for storing items in the world - similar to a Chest
  • MBE31 - a functional container such as a Furnace or Crafting Table
  • MBE32 - an item (bag of flowers) which can store other items inside it. Also shows how to use Capability

Recipes (Crafting/Furnace)

  • MBE35 - some typical example crafting recipes and furnace (smelting) recipes


  • MBE45 - custom commands

Particles - particle effects

  • MBE50 - shows how to use vanilla Particles; also how to generate your own custom Particles


  • MBE60 - send network messages between client and server


  • MBE65 - define new Capabilities and attach them to vanilla objects

Testing tools

  • MBE75 - a tool to help you automate testing of your classes in-game.

Entities and Models

  • MBE80 - Shows the basics of Models (eg PigModel), model parameters adjustable in real time using commands
  • MBE81 - Projectile Entities (eg snowballs, arrows)

Miscellaneous Debugging Tools

  • DebuggingTools- This package is a bunch of functions and tools that I use occasionally, mostly for debugging


  • You can browse directly in GitHub, or alternatively, download it as a zip and browse it locally.

  • If you want to install it and compile it, the basic steps for beginners are:

    1. Download the project as a zip.
    2. Unzip it to an appropriate folder on your computer, such as My Documents. (Or, if you know how to fork a project on GitHub and import it into a local git repository, you can do that instead)
    3. Look at Forge's README.txt file in this folder and follow the instructions to import it into Eclipse or IntelliJ IDEA.
    4. Use the gradle task runClient to run or debug the project.

How to compile and run:

  1. Execute gradle task runClient to test the client installation or
  2. Execute gradle task runServer to test the dedicated server installation. (The first time you run this task it will exit without starting the server. You then need to edit the eula.txt file in the run directory, and execute runServer again.)

If You're Still Confused

Head over here if this didn't make sense to you (check comments for differences with latest versions of IDEA).

With thanks to these helpful folks: alvaropp, yooksi, Brandon3035, twrightsman (greekphysique), Nephroid, Herbix, and Shadowfacts

Licence Info:

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.


For more information, please refer to

  • add new sections to MBE

    add new sections to MBE

    This adds five new sections to MinecraftByExample:

    • mbe07_block_behavior
    • mbe09_ore_spawning
    • mbe10_tool_simple
    • mbe16_item_food
    • mbe17_block_crops

    Ask and ye shall receive! 😄

    These are some new sections we needed for our Minecraft U curriculum. Hopefully, they're all self-explanatory in terms of what they're doing/demonstrating.


    • The READMEs are bare-bones. I can try to find time to expand them as part of this PR, or submit a follow-up PR in a few weeks, once we're underway with our summer camps (things are a little crazy right now). We have written some curriculum around these sections that might be useful in a README. I say might because it is really verbose and hand-holding copy, as it's written for middle-school children.
    • The gaps in your numbering scheme worked in our favor here, except for:
      • Maybe you have other ideas for what those sections should be. I haven't actually looked at all the content on your site. 😬
      • mbe10_tool_simple, which didn't have a different logical spot. I started with a 10_2 scheme but that didn't feel right, so I just created a second mbe10 section. We could just move that example into the main mbe10 folder, but for our students, I felt it was clearer to have a separate folder.
    • Made as few changes to existing code as possible:
      • Removed some extra imports
      • Added to build.gradle to fix IntelliJ issues (our students will be using IntelliJ CE)
    opened by dealingwith 12
  • Need advice on how to make a minigame-style plugin

    Need advice on how to make a minigame-style plugin

    I am a professional game developer, but new to minecraft modding. I'm trying to help my kids make some ideas of theirs come to reality.

    I was very glad to find this repository with great examples on how to get started on modding. But unfortunately none of the examples seem to fit with the kinds of ideas that we have, so I was hoping for a bit of advice on where to get started. We want to make some kind of a minigame, so what I am looking for is a way to add on my own "update loop" where our minigame can contain its own logic. Most of the samples here seem to revolve around creating new types of entities/blocks/recipes for the game which have a specific pattern to them, but it is not clear to me what the correct pattern is for adding in general-purpose code that runs all of the time in the background.

    Here are some of the kinds of things I was thinking we would want the mod to be able to do:

    • Allow several players to connect and join a minigame
    • Present messages on each users screen so they know the state of the minigame (e.g. whether they have joined, what their current score is, etc.)
    • Being able to teleport players to a new location and programmatically create some kind of arena
    • Trading -- some way to alter the contents of players inventory

    We are hoping to make this run on a server where several clients can connect and I don't think we actually need to create new block types etc, so possibly the mod we want to make will be server-only. (We play on hypixel, and the minigames on there don't seem to require a client side mod, they all work just by connecting to their server). I have heard of Bukkit, which seems like it is an alternative way to create server-only mods, but Forge seems like it is more flexible and i get the impression it is more recent/modern, so it would be the way to go even if we were only doing something server side.

    Are there any samples you can point me to of how to create a mod/server like in my examples above? Are there are samples like that in this repo that I missed? Or other resources elsewhere?

    I have already looked at the forge documentation, but it seems a bit slim and I couldn't find any direct answers there for my questions. I have also done a lot of googling and reading random forums populated by 12 year olds that banter back and forth without arriving at helpful conclusions.

    Apologies if this is not the right forum for this question, I just thought I would ask since you have excellent tutorials and you seem to know what is going on.

    opened by uglycoyote 8
  • 1.12.2 mbe05 not working

    1.12.2 mbe05 not working

    Example 05, the dynamic web model, seems to not work in branch 1.12.2 (and probably other earlier branches). When i place the block it just appears as the purple-black missing model block, the item in inventory is appearing normally tough (the cobweb icon).

    I checked the code multiple times, and everything seems fine, but unless i am missing something, there is no such models/block/smartblock/webmodel file in your assets folder, a path which is referenced in block_3d_web_statemapper_name.json as the model path, and is also referenced in the code of ModelLoader3DWeb class.

    So, what is this "webmodel" file supposed to contain? I even tried creating that file myself but still the problem in game persists. I am not even sure why you would have to make a reference to this smartmodel/webmodel file in the statemapper, so because of that missing file in your repository i got very confused. Maybe it got accidentally deleted? If not then i have got no clue how to solve the issue, because the code is identical to yours. Any idea how to solve that? Cheers

    opened by Beethoven92 6
  • Change notes.txt files to files

    Change notes.txt files to files

    Updates the notes files in each section folder to files that will display nicely in GitHub.

    Also updates some formatting to be more markdowny.

    opened by dealingwith 5
  • A sideonly issue in MBE_60

    A sideonly issue in MBE_60

    Since MessageHandlerOnClient uses client only class Minecraft, it would throw a ClassNotFoundException in a dedicated server when MessageHandlerOnClient is loaded. But StartupCommon uses MessageHandlerOnClient. So I doubt whether these codes work on dedicated servers.

    I would use different network registration at dedicated server and client. At client, I would use MBE60 codes:

    simpleNetworkWrapper.registerMessage(MessageHandlerOnServer.class, AirstrikeMessageToServer.class,
                                              AIRSTRIKE_MESSAGE_ID, Side.SERVER);
    simpleNetworkWrapper.registerMessage(MessageHandlerOnClient.class, TargetEffectMessageToClient.class,
                                              TARGET_EFFECT_MESSAGE_ID, Side.CLIENT);

    While at a dedicated server, I would use this:

    simpleNetworkWrapper.registerMessage(MessageHandlerOnServer.class, AirstrikeMessageToServer.class,
                                              AIRSTRIKE_MESSAGE_ID, Side.SERVER);
    simpleNetworkWrapper.registerMessage(MessageHandlerOnServerButHandleClientMessage.class, TargetEffectMessageToClient.class,
                                              TARGET_EFFECT_MESSAGE_ID, Side.CLIENT);

    And define MessageHandlerOnServerButHandleClientMessage:

    public class MessageHandlerOnServerButHandleClientMessage implements IMessageHandler<TargetEffectMessageToClient, IMessage> {
      public IMessage onMessage(final TargetEffectMessageToClient message, MessageContext ctx) {
        throw new RuntimeException("Cannot handle TargetEffectMessageToClient at a dedicated server.");
    opened by herbix 5
  • [Error] Unexpected error 1.16.4

    [Error] Unexpected error 1.16.4

    I build your project and tested it with this1.16.4-forge-35.1.0 Forge Version. After a while i run in that Error net.minecraftforge.fml.common.ObfuscationReflectionHelper$UnableToFindFieldException caused by java.lang.NoSuchFieldException: world.

    Does I miss something? Or is this version still in development?

    The full crash-log.

    opened by chrisvgt 4
  • [SECURITY] Releases are built/executed/released in the context of insecure/untrusted code

    [SECURITY] Releases are built/executed/released in the context of insecure/untrusted code

    CWE-829: Inclusion of Functionality from Untrusted Control Sphere

    The build files indicate that this project is resolving dependencies over HTTP instead of HTTPS. Any of these artifacts could have been MITM to maliciously compromise them and infect the build artifacts that were produced. Additionally, if any of these JAR files were compromised, any developers using these could continue to be infected past updating to fix this.

    This vulnerability has a CVSS v3.0 Base Score of 8.1/10

    This isn't just theoretical; POC code exists already to maliciously compromise jar file inflight.



    To fix: Update your build.gradle so that artifacts are resolved over HTTPS instead of HTTP.

    It seems like this is actually a pretty big issue across the entire Modded Minecraft Ecosystem because there seem to be a lot of mods using this project as a starter structure for their own:

    opened by JLLeitschuh 4
  • .gitignore, and script permissions fix

    .gitignore, and script permissions fix

    Created a .gitignore to ignore all the file and directories generated by gradlew.

    Also, added execute permissions for gradlew bash script, and renamed to

    opened by Lohoris 4
  • Updated mappings

    Updated mappings

    Hi, First off, thank you for your great examples, learned a lot of it. A little remark on your 1.11 branch. You're explaining the use of itemStack.func_190926_b() (for example) and that it will change in the future. It already is changed. You only need to update your mappings in the build.gradle file to something more recent. In the latest mappings all itemStack changes are properly named to increase, decrease, ItemStack.EMPTY and so on.

    It could save everyone some time to read, write and understand the code.

    opened by tomelfring 4
  • Why is there no .gitignore file?

    Why is there no .gitignore file?

    My deepest thanks to all of you for having created this! It is a big help in my minecraft modding endeavour! Though I must admitt that I am very surprised to see that you have no .gitignore file here. Isn't that a very important part of having your minecraft mod on Github? I have had many different suggestions on how I should go forward with the .gitignore file and I am unsure how to go forward...

    I do know that having your mod on Github is by no means a requirement when it comes to modding but knowing how helpful I found looking at the mods here on Github I want to help others going through the same process.

    All of your help would be deeply appreciated!

    opened by TheStoneWolf 4
  • Threaded rendering issue in MBE05

    Threaded rendering issue in MBE05

    As far as I know there are more than one threads rendering the world. But in MBE05, there's only one CompositeModel instance. Since handleBlockState always returns this, different blocks affect each other when rendered in different threads. For example:

    • Thread 1 is rendering one block at A position. Call handleBlockState.
    • Thread 2 is rendering another block at B position. Call handleBlockState.
    • Thread 1 continue rendering. Call getGeneralQuads. Here, states of block at B position is saved, but rendered at A position.

    Solution: Although it costs more space, a new IBakedModel should be returned by handleBlockState, I suppose.

    opened by herbix 4
  • Manually keeping track of .obj entity models

    Manually keeping track of .obj entity models

    The example given in MBE81 for manually keeping track of .obj models is out of date. Some of the interfaces, classes and methods simply don't exist anymore and I couldn't find any replacements.

    Is there any chance we'll get an example of baking .obj models ourselves instead of wrapping them in a block or item in the future?

    opened by FlashHUN 2
  • Incompatibilities with 1.16.5

    Incompatibilities with 1.16.5

    When I try to compile the latest (1.16.4?) version in 1.16.5, I get serious errors such as Material.ROCK not found - it appears that only Material.STONE exists in the Material class.

    Am I doing something wrong?

    opened by FergMcb 1
  • Simple processing machine example

    Simple processing machine example

    Hello! Thanks for the repository with all these useful code examples!

    I would like to see an example for a simple processing machine. Maybe a machine converting a cobblestone into sand by using power. I would like to see the recipe builder for it and maybe some CraftTweaker integration so you can also add custom recipes to it.

    Minecraft version 1.16.5

    opened by DAmNRelentless 1
  • [1.15/1.16] Item Inventory example bugged

    [1.15/1.16] Item Inventory example bugged

    I used the Item Inventory code from your tutorial as a base for Inventory Pets Chest and Feed Bag pets, but then ran into a nasty and unsolved issue:

    Basically, using any inventory item with similar functionality when on a server in creative mode clears the contents of the itemstack inventory. I would remove this example since it has caused significant frustration from players, and does not look like will be solved anytime soon by Minecraft or Forge.

    Since you've written this tutorial, all of the above mods, including Botania, have rewritten their code completely as a result.

    opened by capnkirok 3
Small mod for Minecraft Forge 1.16.5 that sends messages of in-game events to a channel in your Discord server. This mod also enables cross-chatting between Minecraft and Discord.

DiscordSync Small mod for Minecraft Forge 1.16.5 that sends messages of in-game events to a channel in your Discord server. This mod also enables cros

AeonLucid 4 Dec 20, 2022
Minecraft minigame (on working, not a final nor alpha version) HUGE UPDATE COMING SOON

This project is a little minecraft minigame where the goal is either to capture all the ennemies flags or killing all the ennemies, the core gameplay

Laforge 4 Oct 6, 2022
A mixin based ghost client for Minecraft 1.8.9 built on Minecraft Forge.

A mixin based ghost client for Minecraft 1.8.9 built on Minecraft Forge. Originally designed as a MCP Client (called Tephra), it is now being ported t

Peanut 130 Jan 1, 2023
A free mixin-based injection hacked-client for Minecraft using Minecraft Forge.

Custom LiquidBounce 1.8.9 build that aims to improve original visuals and bypasses, along with built-in ViaVersion to help you change from 1.8 to 1.17.1 without creating any other version branch.

epic group of paster 123 Jan 2, 2023
This code contains very basic implementation of Tetris game

SeoulTech SE Course Team Project - Tetris reference code. This code contains very basic implementation of Tetris game. Use it only for reference of ho

null 8 Sep 30, 2022
Mesh is a cross-version minecraft mod development platform for Forge and Fabric.

Mesh is a cross-version minecraft mod development platform for Forge and Fabric. Supported Versions Mesh will eventually be able to run on most f

null 12 Dec 13, 2022
LoliServer 是 Minecraft 较新版本 1.16.5 中的 Forge + Bukkit 服务端核心, 支持Forge Mod和Bukkit 插件, 兼容性与性能优秀, 于Mohist1.16.5基础加以维护更新

LoliServer 1.16.5 LoliServer-1.16.5,基于Forge并融合Paper/Spigot/Bukkit的高性能高兼容性的服务端核心 上游项目 Mohist Bukkit Paper CraftBukkit Spigot MinecraftForge Atom Thermo

LoliServer 0 Apr 29, 2022
sexc forge mod for 1.12.2 minecraft

Wurst+3 Discord | Donate | Download 1.12.2 forge minecraft client Made for crystalpvp and killing noobs. On first run ensure your voices volume is max

Wurst+ 203 Dec 9, 2022
A minecraft forge lib that is used by most of my mods.

MatyLib A minecraft forge lib that is used by most of my mods. Installing (for modders) Before installing, please decide on what version you want, by

matyrobbrt 2 Jan 7, 2022
Addon to the Minecraft Forge/Fabric mod InvMove that adds mod compatibilities

Addon to the Minecraft Forge/Fabric mod InvMove that adds mod compatibilities

David M. 3 Oct 21, 2022
Minecraft Forge/Fabric mod that adds the ability to walk around while in inventories

Minecraft Forge/Fabric mod that adds the ability to walk around while in inventories

David M. 16 Nov 22, 2022
Minecraft Forge Hybrid server implementing the Spigot/Bukkit API (Cauldron for 1.18)

❓ About Magma is the next generation of hybrid minecraft server softwares. Magma is based on Forge and Paper, meaning it can run both Craftbukkit/Spig

Magma Foundation 12 Apr 18, 2022
A Minecraft Forge Mod that adds the features from Blockixel Artistry's YouTube videos

Blockixel Concepts for Forge 1.18.2 Fabric Port at A Forge mod that aims to implement Blockixel

OutCraft 3 Dec 25, 2022
Operadora - A Minestom server implementation with basic features and supreme modularity <3

Operadora Operadora is a a Minestom server implementation with basic features, some utilities and full modularity. <3 Installation Download the latest

Zak Shearman 4 Dec 30, 2022
The most powerfull forge server software (not yet) which aims for high capacity and performance on 1.16.5 modded server.

GoldenForge The most powerfull forge server software (not yet) which aims for high capacity and performance on 1.16.5 modded server. Current work Asyn

null 20 Sep 3, 2022
A 1.7.10 Forge Mod to allow players to access easy stats like latency, FPS, and CPS

EZStats A 1.7.10 Forge Mod to allow players to access easy stats like latency, FPS, and CPS. Currently a work in progress, all code is accessable in t

applesfruit 4 Aug 8, 2022
A Forge mod that implements SpongeAPI

SpongeForge Currently not stable and under heavy development! A Forge implementation of the Sponge API. Homepage Source Issues Documentation Community

SpongePowered 1.1k Dec 20, 2022
A base for Forge 1.12.2 utility mods to use.

ClientBase Why? I made this for learning and for use in my private client TO-DO Add ClickGUI Add HUD and HUDEditor Add Javadocs How to use?

ZWare 50 Dec 2, 2022