Basic Modding

From Minecraft Forge
Jump to: navigation, search

Warning Icon.png

This page is marked as Outdated.

It was made for older content and may cause problems.

Please improve this article if you can.


How-To Icon.png

This is a How-To guide or Tutorial detailing a practice or process for Minecraft Forge or related software.

Generic Mod

Havvy Generic Mod Banner Final.png

October 9, 2014 Added metadata support in localising tutorial --SkylordJoel

March 27, 2014 Updated Basic Items to 1.7.x --Jwosty

February 13, 2014 1.7 update happen and I fix up some of the stuff so far:

But it has one part not working yet


July 5, 2013

1.6.1 came out so I have fixed up some of the basic tutorials to go with it.

Ones that are updated include:

-- Mew

March 13, 2013

1.5 came out, so I fixed the methods to account for this (mostly the Icons/Textures tutorial).


December 13th, 2012

Alright, Forge made their installation process really simple and also made proper packages, removing the common/src distinction. I rewrote most of Basic Modding to account for this update. Overall though, this simplifies the explanations, but imports changed in all tutorials. Next up, I need to finish the world gen tutorial.

With the Basic Modding tutorial being mostly rewritten, if anything is confusing about it now, please tell me ASAP!

December 3rd, 2012

I finally finished the tutorial on Plants I started a month ago. I also fixed a minor compilation bug in Packet Handling. I reorganized the Generic Ore section by adding a Dropping Ore section. I'm starting to use a General Knowledge template where the background is grey. The knowledge in those boxes are general facts that are not specific to whatever thing we are implementing. I updated the Textures and Icons section to say that the image can be any scalar of 16x16 pixels where 256x256 will have each icon be 16x16 in size.

Getting Started

Welcome to modding minecraft! We modders have a lot of control over Minecraft, but there's a lot of code and beginning can be overwhelming. But still, creating your own blocks and adding your own functionality to Minecraft is quite a liberating experience! If you don't like a facet of the game, change it! If you want more content, you can add it! These tutorials are meant to ease you into modding Minecraft by teaching basic concepts that are useful for most modders.

If you are more of a visual learner, here is a playlist of video tutorials that follow this series:


  • To understand how to find Minecraft code you care about.
  • How to create packages and classes in Eclipse
  • To have and understand the boilerplate for a Minecraft mod


  • Have Installed your Forge development environment
  • Know how to program in Java. If you don't, start learning Java. You can probably pick it up while writing mods, but don't ask for Java help in Minecraft communication channels. There are entire books on learning Java, along with online tutorials.


This tutorial is a more descriptive form of Wuppy's third and fourth tutorial. The tutorials have code, but does not explain why the code exists in a satisfactory manner. A lot of these tutorials also have analogs to Wuppy's tutorials.

For another location of source code, the master source for the Generic mod can be found on GitHub including all resources. If you cannot get the master source to work, file a bug on GitHub. If you think that the master source and the wiki source are out of sync, also file a bug.

The Generic Mod is made by Havvy, so if you have questions you want answered in real time, you might find him in the MinecraftForge IRC channel, amongst other places. He's friendly most of the time, but if you ask basic Java questions, be prepared to be told to go learn Java.

Case Matters

When you see a name, its capitalization matters. If it's all lowercase, it's all lowercase for a reason. Same for whether it starts with an Uppercase or if its is camelCase.

Most of the time, its to follow Java's capitalization standards which makes sharing readable code easier. If you throw code up in public and it doesn't follow Java's capitalization standards, I, Havvy, will look at you strangely. Mostly this happens when classes are camalCase instead of TitleCase.


Workspace Woes
If you picked the wrong folder for your workspace, or already use Eclipse with another workspace, you can create a new workspace by going into File -> Switch Workspace -> Other...

These tutorials assume you are using Eclipse. While you don't need Eclipse, and you could use IntelliJ, NetBeans, Emacs, Vim, or something more primitive, the people who make Minecraft modding actually possible for the majority of programmers have set up special support for getting started in Eclipse. So, if you have not done so yet, download Eclipse. Unfortunately, it is a huge program, and also requires quite a lot of system memory. But what it eats in system resources, it gives back in awesome Java tools. When you first run Eclipse, it'll ask for a workspace. Make sure that you point it to /forge/mcp/eclipse. For Forge 1.7/1.8 use "/forge/eclipse".

When you do so, Eclipse will start with one project "Minecraft" already in its Package Explorer on the left side of the screen. Expand the project, and you will see a source directory named 'src'. Expand it, and you'll see quite a lot of packages that make of Minecraft and Minecraft Forge. While you will not be editing any of these classes, feel free to read these classes to figure out what you can do or to see how Minecraft works.

Creating Packages and Classes

Modding with Forge means that all modifications are done via adding new classes. At no point, unless you are making a coremod and have a really good reason, should you be editing any other class. The classes you add should be in their own package.

Your Own Mod
You may use a different package name if you are creating an actual mod. For package names, I suggest yourname.yourmodname or yourname.minecraft.yourmodname depending on how much you program in Java, and want to avoid package name conflicts.

To create packages and classes in Eclipse, we right click the containing context in the Package Explorer we want the package or class to be in. For packages, this is the src directory. For classes, this is the package the class belongs to. This context allows Eclipse to pre-fill in some required configuration. When we right click on the context, we select New -> Package or New -> Class.

For the Generic mod, we will use the package tutorial.generic. If you are following along with this tutorial exactly, create that package by selecting Package on the New menu. In the popup that opens, make sure the source folder is Minecraft/src and that the name is tutorial.generic. Once done, the package explorer should now show that an empty package tutorial.generic exists.

Next up, we shall create the first class of any mod: the Base Mod file. This class contains the hooks that Forge will use to bind your mod to Minecraft. As our mod for these tutorials is the Generic mod, this class will be called Generic.

Right click on the tutorials.generic package, and create a new class. The only things that matter on the dialog are the source folder, package, and name. The source folder is Minecraft/src. The package is tutorial.generic. The name is Generic.

At this point, you should have a class called Generic in the tutorial.generic package in the Minecraft/src directory. If you do not, please try again.

Source Location

You will find the packages and classes you created at /forge/mcp/src/Minecraft/.

Base Mod Class

The Base Mod class is the class that Forge loads. All your other classes will have to be registered to Forge from the base mod making it the central location for your mod. For this reason, I suggest naming the base mod class the same name as your mod. Since this tutorial series works on the Generic Mod, this class is named Generic.

In the last section, we created an empty class. Let's flesh this class out with the standard boilerplate of a mod. Replace whatever Eclipse generated with the following section.

View the page source to see a version for Minecraft 1.7.

<syntaxhighlight lang="java"> package tutorial.generic;

import net.minecraftforge.fml.common.Mod; import net.minecraftforge.fml.common.Mod.EventHandler; import net.minecraftforge.fml.common.Mod.Instance;

import net.minecraftforge.fml.common.SidedProxy;

import net.minecraftforge.fml.common.event.FMLInitializationEvent; import net.minecraftforge.fml.common.event.FMLPostInitializationEvent; import net.minecraftforge.fml.common.event.FMLPreInitializationEvent;

@Mod(modid=Generic.MODID, name=Generic.MODNAME, version=Generic.MODVER) //Tell forge "Oh hey, there's a new mod here to load." public class Generic //Start the class Declaration {

   //Set the ID of the mod (Should be lower case).
   public static final String MODID = "generic";
   //Set the "Name" of the mod.
   public static final String MODNAME = "Generic Mod";
   //Set the version of the mod.
   public static final String MODVER = "0.0.0";
   @Instance(value = Generic.MODID) //Tell Forge what instance to use.
   public static Generic instance;
   public void preInit(FMLPreInitializationEvent event)
   public void load(FMLInitializationEvent event)
   public void postInit(FMLPostInitializationEvent event)

} </syntaxhighlight>

Now that we've got that out of the way, you'll notice that there are a lot of @annotations and import statements (which will only get longer as you continue to mod and add more content to your mod); This is the absolute basis for creating a Mod for 1.8, But it won't do anything (at least, not yet).

Base Mod Annotations

This base mod class probably has you asking questions. Hopefully this section answers them. This section is a list of the annotations used in the Base Mod class and what they actually signify.

Tells Forge that this is the Base Mod class. Takes three parameters.
  • modid 
    A unique name for your mod. Should never be changed after your initial release.
    Human readable name for your mod.
    The version of your mod. Pick any versioning scheme you want.
Hat tip to Wuppy for this description.
Tells Forge how to handle what happens when the client xor the server has the client installed. Takes two parameters.
  • clientSideRequired 
    Asks if you need this on the client to use this mod. This should be true.
    Asks if you need this on the server for the client to be able to connect. This should always be false, else you can't join a server if the server doesn't have the mod installed, but you do. It is false by default anyway.
    Removed as of 1.7
Base Mod classes are Singletons. This is the object reference to your class that Forge uses. Make sure that the argument is the modid in @Mod. Otherwise, it'll default to the empty string, and cause problems with any mod that also does that.
This proxy is where Forge decides which class to load depending on whether or not the client or server is running. You can use this annotation on any field.
  • clientSide 
    String containing the fully qualified name of the class to load for the client.
    String containing the fully qualified name of the class to load for the server.
This gets called on all the methods. It is 1.6.1's equivalent to @PreInit, @Init, and @PostInit. (Note that the FML events stay the same, only the annotations get changed)
For 1.6.X, need to add the following import cpw.mods.fml.common.Mod.EventHandler;

If you need help understanding this part, check out this video tutorial:


At this point, you should have the following in your Package Explorer (in addition to all the minecraft and minecraftforge packages):

  • Minecraft
    • src
      • tutorial.generic

If so, you have successfully set up the boilerplate for a Forge mod, and are ready to start adding your own content.

To test your mod: Save your workspace, then press the green Run button. Minecraft should launch with your mod installed.

What's Next?

In future tutorials, there will not be as much copy pasting of entire classes. Instead, the class will be built up, with the final cleaned up result shown at the end.