Home

This is BurlapCraft, a mod aimed at using Minecraft as a test bed for artificial intelligence by integrating with BURLAP, the Brown-UMBC Reinforcement Learning and Planning library. BurlapCraft is built using BURLAP and [Minecraft Forge][www.minecraftforge.net], a Minecraft API that contains hooks into base Minecraft files. In the current release, the mod contains two dungeons, each with a specific goal that the agent needs to reach by maximizing its reward. We used BURLAP to use both planning algorithms (to solve the dungeon with a hard-coded model) and reinforcement learning algorithms (to learn the model) to solve the two dungeons within Minecraft. We also provide instructions for creating new dungeons of your own within Minecraft.

To try BurlapCraft, you will need to install Minecraft Forge. WikiHow has a step-by-step tutorial for installing Minecraft Forge and adding mods. Once you have Forge set up, you will need to drag the BurlapCraft jar file into the mods folder and you will be good to go. We recommend disabling other mods before trying BurlapCraft.

This post is aimed at guiding you through the process of getting set up with BurlapCraft, creating dungeons and solving them using BURLAP.

Installing BurlapCraft

• You will need to get a copy of Forge source to setup your dev environment. You should get the recommended version of 1.7.10 here. After it has downloaded, extract its contents (rename this folder to forge for convenience).

• Fire up your terminal/command window and navigate to the forge folder using the 'cd' command. Once you are within the forge folder in the terminal/command window, you will need to run the following command: gradlew setupDecompWorkspace --refresh-dependencies This will download all the requirements to begin modding using Minecraft Forge.

• If you are on Linux or Max OS, you should always use './gradlew' instead of 'gradlew'. If this does not work, you can retry after running 'chmod +x gradlew'.

• This guide uses Eclipse because it is the general preference for an IDE within the Minecraft modding community. To set up the eclipse development environment, run the following command from within the forge folder: gradlew eclipse

• Once Eclipse is setup, your forge folder should contain the code for the example mod and should be good to go. To look at the code for the example mod, open Eclipse using the eclipse subdirectory within the forge folder as your workspace.

• Once you acquaint yourself with the structure of the example mod, you can download the latest version of BurlapCraft by pressing the 'Download as zip' button at this link. After it has downloaded, extract its contents (if this folder is not called 'src', rename it to 'src').

• Navigate to the forge folder and replace the src folder within it with the one you just downloaded. On refreshing or reopening Eclipse, you should see a new package for burlapcraft that contains all the java classes being used for the mod.

• You might see a lot of errors within the project. This is because you need to add the BURLAP java code library to your project to resolve the missing dependencies. You can download BURLAP here.

• Once you have the BURLAP jar file, import it. This should resolve all the errors.

Structure of BurlapCraft

There will be a lot of BURLAP talk henceforth so this is a good time to go through a basic tutorial here.

• If you open Minecraft in your IDE, you should see a src/main sub directory within which you will find the com.kcaluru.burlapcraft package. This package contains all the java classes being used for the mod. The resources being used for the mod (for example: textures and names of user created blocks or items) are within the resources folder inside src/main. For the purpose of creating a new dungeon and solving it, you will not need to worry about the resources folder.
• BurlapCraft.java is our base mod class that contains some basic mod information (like the name and version) and also contains the initialization events. The code within the initialization events gets executed when you run the mod.
• Custom items and blocks that we created are stored in the item and block packages respectively. All the helper classes are within the helper package.
• We are using a real and a simulated domain for the purpose of learning and planning respectively. We map the simulated domain to the real domain to run actions actual Minecraft for planning. MIGHT NEED TO EXPLAIN OUR DOMAIN, ACTIONS, ETC. CREATE A SEPARATE DOC FOR THIS? THIS PAGE IS VERY LENGTHY ALREADY.

Creating a Dungeon

• You can use any name for your dungeon. For the purpose of convenience within this guide, we are going to call it 'Bedrock'. Create a new class named 'DungeonGeneratorBedrock' within the dungeongenerator package. Copy over code from one of the other dungeon generators and fix the errors by renaming the class and the constructor.
• The generate method creates the dungeon within Minecraft by setting a block at each (x, y, z) coordinate. We will modify this later.
• Open the HandlerDungeonGeneration within the handler package. Create three new public static variables - BedrockX, BedrockY and BedrockZ.
• Go down to the generateSurface method and initialize them to coordinates relative and close to the player coordinates. This will ensure that the dungeon renders as soon as the world is loaded because it is close to the player.
• Call the generate method on a new instance of your DungeonGeneratorBedrock class and pass it the following parameters - world, random, BedrockX, BedrockY and BedrockZ.

If the dungeon you have in mind is very simple then you can just replace the code within generate with for-loops that set each block as you desire. You can skip ahead if used for-loops for generation.

Generation

• For this section, you will need to download MCEdit from here and a Schematic Converter from here.

• Once you have MCEdit, you have two options:

  • Create the structure in MCEdit itself (generally good for large landscapes).
  • Create the stucture in a Minecraft world and then export the schematic for it using MCEdit (generally good for smaller 'dungeon-sized' structures).

• Let us go ahead with option 2. Run Minecraft from Eclipse, create a new world in creative mode (name the world something you can identify easily) and create your structure manually.

• After creating your structure, you can close Minecraft. Go back to MCEdit and press the 'Load World' option. We are looking for the level.dat file of the world you just created. You should be able to find it in the eclipse/saves/(your world's name) subdirectory within the forge folder.

• Once you load the world, you need to select the dungeon structure you created from end to end and export it. Use the 'w-a-s-d' and 'i-j-k-l' keys in conjunction to navigate around the model of the world you are looking at. Press and hold the left mouse button and drag to select multiple blocks.

• After selecting your structure, press export and save the schematic file to any location (I have a schematics folder within my forge folder where I like to store all my exported files).

• Place the Schematic Converter jar file you downloaded into the same folder where you are saving your schematics. Fire up your terminal/command window and run the Schematic Converter using 'java -jar SchematicConverter.jar'.

• Choose 'New', then 'Open File' and point it to the schematic file you just created. Do not check the 'Ignore Air' option. Press 'Convert File'. It should say 'successfully converted file'. Press 'OK' and then press 'Save Code'. We will use this code within the generate method.

• Replace every line of code within the generate method (in the DungeonGeneratorBedrock class) except the return statement with the lines within the spawn method of your saved code.

• If you run Minecraft from your IDE, you should be able to find the dungeon you created when you create a new world and join it. Remember to use coordinates close to the player for the dungeon so that you can find the dungeon easily.

Solving the dungeon

• Open the HelperNameSpace class in the helper package. Add your dungeon name (all lower case) to the end of the dungeonNameList array. We will be using this array to keep track of dungeons.
• Next, open the StateGenerator class in the stategenerator package. Create three new static variables storing the dimensions of your dungeon. Scroll down and create another else-if clause that checks if the dungeonID is the same value as the index of your dungeon name within the dungeonNameList array that you just modified. Within the else-if set dungeonX, dungeonY and dungeonZ to HandlerDungeonGeneration.bedrockX, bedrockY and bedrockZ respectively. Then assign the dimension variables you created to length, width and height.
• Now, go to the CommandTeleport class in the command package and add a new case, for the array index of your dungeon name within the dungeonNameList, in the switch statement for dungeonID. Within the case, set reasonable x, y, z coordinates for the player relative to (0, 0, 0) for the cornermost block in the dungeon. These coordinates will be used to teleport the player to the specified (x, y, z) position within the dungeon when you type '/tele (your dungeon name)'.

Solving

• To solve the dungeon you created, you will need to create a new Solver class within the solver package. Make sure that the name of your class contains either 'Planning' or 'Learning' within it or create two separate classes if you wish to try both. Copy over code from one of the Solver classes for the other dungeons and make changes as you see fit for your dungeon (for example: remove BFS if you do not wish to try it or try one of the other algorithms that BURLAP has).
• Your dungeon might also require you to add new actions or object classes. You can do this within the DomainGenerator classes within the domain generator package. The Real generator is currently being used for learning algorithms and the Simulated one for planning algorithms.
• In case you are trying algorithms other than BFS, AStar or RMax, create new Command classes for the algorithms within the command package. Once again, you can refer to the code written for the BFS, AStar and RMax command classes to write your own. Feel free to get as creative as you can!

Useful Commands

• If you want to test out the mod in Minecraft, you can build your mod and zip it into a .jar file by running 'gradlew build' in your terminal/command window from within the forge folder. You can find the .jar file in the 'build/libs' subdirectory.
• If you want to launch Minecraft with your mod installed, you can run 'gradlew runClient' in your terminal/command window from within the forge folder.