日志

2013-01-23

已有 173 次阅读2013-1-23 11:51

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.

[edit]Goals

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

[edit]Prerequisites

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.

[edit]Credits

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.

[edit]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.

[edit]Eclipse

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.

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.

[edit]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 suggestyourname.yourmodname oryourname.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.

[edit]Source Location

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

[edit]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.Init;
import cpw.mods.fml.common.Mod.Instance;
import cpw.mods.fml.common.Mod.PostInit;
import cpw.mods.fml.common.Mod.PreInit;
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 cpw.mods.fml.common.network.NetworkMod;

@Mod(modid="Generic", name="Generic", version="0.0.0")
@NetworkMod(clientSideRequired=true, serverSideRequired=false)
public class Generic {

  // The instance of your mod that Forge uses.
@Instance("Generic")
  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;

@PreInit
  public void preInit(FMLPreInitializationEvent event) {
  // Stub Method
  }

@Init
  public void load(FMLInitializationEvent event) {
proxy.registerRenderers();
  }

@PostInit
  public void postInit(FMLPostInitializationEvent event) {
  // Stub Method
  }
}

SidedProxy

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

[edit]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.

@ModTells 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.name Human readable name for your mod.version The version of your mod. Pick any versioning scheme you want.

@NetworkModHat 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.serverSideRequired 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.

@InstanceBase 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.@SidedProxyThis 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.serverSide String containing the fully qualified name of the class to load for the server.

@PreInitThis method is called before @Init. This is where reading configuration files goes.@InitThis is where the majority of your Mod initialization will go. Block and item registry, WorldGen registry, and crafting recipes are common things found here.@PostInitThis is where code goes for working with other mods. For example, your initial configuration of block ids so that you can claim ids no other mod uses.[edit]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 {
  public static String ITEMS_PNG = "/tutorial/generic/items.png";
  public static String BLOCK_PNG = "/tutorial/generic/block.png";

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

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 {

@Override
  public void registerRenderers() {
MinecraftForgeClient.preloadTexture(ITEMS_PNG);
MinecraftForgeClient.preloadTexture(BLOCK_PNG);
  }

}

Inheritance Woes

Any methods not overloaded 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.

[edit]Finished

At this point, you should have the following in your Package Explorer: