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 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.

package tutorial.generic;

import cpw.mods.fml.common.Mod;
import cpw.mods.fml.common.Mod.EventHandler; // used in 1.6.2
//import cpw.mods.fml.common.Mod.PreInit;    // used in 1.5.2
//import cpw.mods.fml.common.Mod.Init;       // used in 1.5.2
//import cpw.mods.fml.common.Mod.PostInit;   // used in 1.5.2
import cpw.mods.fml.common.Mod.Instance;
import cpw.mods.fml.common.SidedProxy;
import cpw.mods.fml.common.event.FMLInitializationEvent;
import cpw.mods.fml.common.event.FMLPostInitializationEvent;
import cpw.mods.fml.common.event.FMLPreInitializationEvent;
//import; // not used in 1.7

@Mod(modid="GenericModID", name="Generic", version="0.0.0")
//@NetworkMod(clientSideRequired=true) // not used in 1.7
public class Generic {

        // The instance of your mod that Forge uses.
        @Instance(value = "GenericModID")
        public static Generic instance;
        // Says where the client and server 'proxy' code is loaded.
        @SidedProxy(clientSide="tutorial.generic.client.ClientProxy", serverSide="tutorial.generic.CommonProxy")
        public static CommonProxy proxy;
        @EventHandler // used in 1.6.2
        //@PreInit    // used in 1.5.2
        public void preInit(FMLPreInitializationEvent event) {
                // Stub Method
        @EventHandler // used in 1.6.2
        //@Init       // used in 1.5.2
        public void load(FMLInitializationEvent event) {
        @EventHandler // used in 1.6.2
        //@PostInit   // used in 1.5.2
        public void postInit(FMLPostInitializationEvent event) {
                // Stub Method
If you copy this verbatim, but don't have the proxy classes, it may be possible for the mod to work for single player, but not for multiplayer. As such, make sure the proxy classes are created as described in the next section.

That's a lot of imports and annotations, no? The import list will only get longer with each additional tutorial you follow. Generally, Eclipse will handle imports for you, so I will not explicitly say to add import statements.

There WILL be an error when you copy this code. CommonProxy should be underlined red. This is because it will be created in the Proxy Classes section.

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.
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:

Proxy Classes

Minecraft uses a client and server setup, even on single player. The server side does all the work maintaining the world's state while the client renders the world. The thing is though, that all code runs on both the client and server side unless specified otherwise. There are two annotations for specifying code be ran on only one side.

The annotation @SidedProxy is used when you want the server to call the constructor of one class and the client another. Both classes need to be the same type or subtype of the field, and the names of the classes are passed as Strings. In the Base Mod we see the annotation used like this:

@SidedProxy(clientSide="tutorial.generic.client.ClientProxy", serverSide="tutorial.generic.CommonProxy")
public static CommonProxy proxy;

While I'm not sure when or where the proxy is actually instantiated, if it is on the server side, it'll call the default constructor of tutorial.generic.CommonProxy and if it is on the client side, it'll call the default constructor of tutorial.generic.client.ClientProxy.

We use the proxy for registering images and hosting our GUI handler.

First we will start with the server side of the proxy. As from reading the above code, the class is found at tutorial.generic.CommonProxy. Create the CommonProxy class in that package, and place this skeleton in it.

package tutorial.generic;

public class CommonProxy {

        // Client stuff
        public void registerRenderers() {
                // Nothing here as the server doesn't render graphics or entities!

For the client side of the proxy, it was decided to place it at "tutorial.generic.client.ClientProxy". Neither this package (tutorial.generic.client) nor the class (ClientProxy) exist yet.

Create the package tutorial.generic.client. Then, add ClientProxy to the package using this for source.

package tutorial.generic.client;

import net.minecraftforge.client.MinecraftForgeClient;
import tutorial.generic.CommonProxy;

public class ClientProxy extends CommonProxy {
        public void registerRenderers() {
                // This is for rendering entities and so forth later on
Inheritance Woes
Any methods not overridden in ClientProxy will act the same as CommonProxy. Don't let that inheritance bite you.

The actual reason for these fields and the registerRenderers method are explained in the Icons and Textures tutorial. For now, those images do not exist.


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
        • Generic
        • CommonProxy
      • tutorial.generic.client
        • ClientProxy

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.

Personal tools