Installing a Minecraft Mod Development Environment

Mark “Mak” Roberts

This document walks you through setting up the development environment for building minecraft modifications (aka mods) using files from the ActorSim repository. Mods are written on top of a toolset called Forge ( This guide walks you through setting up a specific version of forge for Minecraft 1.7.x. However, we also have the files available to install Forge for Minecraft 1.8.x - to install for this version, simply replace 1.7 with 1.8 as appropriate. This guid installs the tutorial code we used to learn the Forge framework as well as the MinecraftConnector project we use to link Minecraft to ActorSim.

For your reference, the official Minecraft distribution, running without any mods, is called Vanilla Minecraft by modders. This guide was adapted from the Minecraft Forge instructions and several videos by Kenneth Goodin.

Install Vanilla Minecraft

The first step is to install a working version of Minecraft with a valid user account. Instructions for this can be found at You must run this at least once and create a new world.

Install the ActorSim Development Environment

You must also have already installed the ActorSim development code. If you installed ActorSim, you should have a directory c:sworkspaceactorsim.git. From now on, we will refer to that directory as ACTORSIM_HOME.

Install the Forge Library

  • In ACTORSIM_HOME lib you will find several files starting with forge.

  • Run the Forge installer

  • Launch Minecraft and select the Forge profile then select Edit Profile.

  • Select the proper version of Forge in the Use Version drop down box. Note that it may be at the bottom of the list.

  • Optionally, you can also select to increase your JVM memory using the JVM Arguments.

  • Click Save then Play and confirm that you have correctly installed Forge by looking at the FML version in the lower left of the Minecraft start screen.

Install and Build the Forge Source

  • In the same ACTORSIM_HOMElib directory, you will find the file for the same version of Forge that you just installed. Extract it to forge-src-1.7.

  • On windows:

    • Go into the source directory, then Shift-Right-Click the window and select Open Command Window here.
    • Run the command: gradlew setupDecompWorkspace eclipse –refresh-dependencies (note that there are two dashes before refresh)
  • On linux

    • Run the command: `./gradlew setupDecompWorkspace eclipse --refresh-dependencies` (note that there are two dashes before refresh)
  • You should see something like: .. image:: ../../images/install-forge/gradle.png

  • You will know it is correct if the last line states BUILD SUCCESSFUL. Otherwise, review the errors and try again.

  • NOTE This can take 10-20 minutes to perform the first time because it: (1) it decompiles a library of deobfuscated Minecraft code, (2) creates the ForgeAPI we will use to code the mod against, and (3) sets up an eclipse project that we will later import into our development environment.

Importing Forge and ActorSimMC Mod Projects into Eclipse

  • Open Eclipse and select File->Import. Select General and Existing Projects Into Workspace.

  • Enter the root directory as: ACTORSIM_HOMElibforge-src-1.7

  • Select the forge-src project

  • You should see the force-src-1.7 project in your workspace with no compile errors.

  • Again select File->Import and then select General and Existing Projects Into Workspace.

    • Enter the root directory as: c:sworkspaceactorsim.giteclipse-projects
    • Select the MinecraftTutorial-1.7 and ActorSimMC-1.7 projects.
    • You should see now the projects in your workspace with no compile errors.

Minecraft Developer Tips

I recommend you start by working in creative mode in a super flat world. When you start a new world, select the Creative Mode, then select “More World Options” then “WorldType:Superflat”. Animals and mobs will spawn on the default superflat world because it has grass. You can turn off mob spawning by typing the following at the game console: /gamerule doMobSpawning false Alternatively, we can set up a more desirable world, since this world is easy to fall out of if you break too many layers below you. To do so, use the following preset string, which creates a world of bedrock (ID=7) with 15 layers of Double Stone Slab (ID=43)).


You could also use dirt (ID=3), Block of Iron (ID=42), or Oak Wood (ID=162). Some blocks are lightly colored or borderless, making movement or the debug screen hard to see. The oak has a pattern that makes it easy to see which way west is but wood is flammable (you’ve been warned not to start a fire or place lava on the wood, but I already know you’ll try it anyway!).

A useful list of Minecraft block ids can be found at: A list of useful game commands can be found at:

Minecraft Coordinates

The world coordinate system of Minecraft follows the so-called right-handed coordinate system commonly used in computer graphics. Imagine that the thumb is the X axis, the index is the Y axis and the middle finger the Z axis. The values in this system increase in the direction of each finger. These three axes are bound such that East is along the increasing X axis (i.e., the thumb), up is along the Y axis (the index finger). An easy way to remember this is that X is east like it would be on a map oriented to the north. However, Y is up like it would be on a graphing paper.

The local coordinate system of any entity in Minecraft, which includes the camera, is determined using the Roll-Pitch-Yaw (RPY) coordinate system. It is easiest to imagine the camera pointing in the X direction (i.e., to the east). Rolling is rotation about the X axis, pitching is rotation about the Y axis, and yawing is rotation about the Z axis. It might be easiest to consider that RPY applies to the right hand similar to the way XYZ apply to the right hand, but remember that the object being rotated faces in the positive X direction (i.e., Easterly).

Both yaw and pitch are measured in degrees.

Minecraft Connector

The minecraft connector is your main interface into controlling the world state and the character.

Minecraft Connector Commands

The set of commands that can be given to the character are found in the MinecraftConnector project in the package This document overviews some of these commands and you are encouraged to look in this package for more details.

The “/setTarget N” command sets a target block N blocks to the north. You will see a gold block appear under the target block.

The “Do” command is the most useful for many commands; see for a complete list. In order to run many of the subcommands you must have a target set, which is done by either by setting the target using /setTarget or creating an obstacle course using /makeObstacle. - /do bridge -> Places a block in the ground to create a “bridge”

  • Preconditions: Block on the ground in front of the player must be lava or water
  • /do stairs -> Moves back one step and places a block in front to create a staircase - Preconditions

    • Should be able to move back one step
    • Blocks at leg height and eye height behind the player should be air, and block on the ground should be walkable
  • /do mine -> Mines two blocks in front of the player - Preconditions

    • The blocks at foot level, eye level, and one block above the eye level should not be air
  • /do stepTo -> Walks forward toward the target - Preconditions

    • Blocks at foot and eye height should be air, block on the ground should be walkable. - If block on the ground is air, then there should be block that is not air by the third block down
  • /do walkAround -> Walks to the nearest available block - Preconditions

    • Should be at least one block in the 8 compass directions that the player can move to and has not visited before
    • Uses the same preconditions as WalkTo For a more complex target, you can create obstacle courses.
  • Command for creating sections - “/makeSection sectionName” -> Creates the specified section to the north of the player

    • sectionName is one of the types from the file.
    • There are 9 different sections. The first 5 sections were used for experimentation - Lava -> A pool of lava is in the middle of the section. - Pond -> A pond is in the middle of the section - Short Wall -> A wall of height 2 is in the middle of the section. - Tall Wall -> A wall of height 3 is in the middle of the section - Obstacle -> An “obstacle” is in the middle of the section - Empty -> A blank section - Stairs -> A staircase - Arch -> A horizontal beam at height 2 - Comb -> A comb of height 3 facing the player
    • Created in the file
  • Command for creating obstacle courses - “/makeObstacle N” -> Creates a random obstacle course of N sections

    • N is any positive integer (though low numbers are better!)

We created five strategies for selecting subgoals - Commands for running procedures

  • Expert Procedure - “/takeExpertMove N” -> Runs the ordered procedure to a specified target N times. If N is -1, this command will loop until at the target.

    • Created in the TakeOrderedMove
  • Ordered Procedure - “/takeOrderedMove N” -> Runs the ordered procedure to a specified target N times. If N is -1, this command will loop until at the target.

    • Created in the TakeOrderedMove class

TODO Update command list