Minecraft Overview

Minecraft is an open world game originally created by Markus “Notch” Persson. There is no set objective in Minecraft. Rather, players can interact with the game in ways that suit their interests. Activities a player can perform during play include (1) exploration of the world, (2) mining of various substances such as wood, iron, coal, and diamond, (3) gathering of food, (4) crafting, and (5) combat.

Architecture

Minecraft has a client-server architecture. Specifically, a Minecraft world resides on a server, and players can connect to a Minecraft world using a client.

A typical way of playing Minecraft is to use the Minecraft launcher (the software you downloaded from Mojang) to join a Minecraft world. There are many options possible. For example, you can create your own world and join it (i.e., enter the world you created). In this case, both the server and the client will be running on your machine. It is also possible to connect your client to an online server.

CanaryMod is a Minecraft server that you can install on your machine. An interesting feature of CanaryMod is that it has a plugin API which allows its behavior to be customized. This ability to perform customization distinguishes CanaryMod from a standard vanilla Minecraft server.

Bricklayer is integrated with Minecraft through a CanaryMod plugin called RasberryJuice. This plugin is a PC implementation of the key functionality of the Minecraft: Pi Edition modding API (the Pi Edition is a free version of Minecraft developed by Mojang for the Rasberry Pi computer).

The RasberryJuice plugin provides a function, called setBlock, capable of placing a block at a particular position in a Minecraft world. In order for setBlock to work, the Minecraft world in which the block is to be placed must reside on the CanaryMod server. Another important RasberryJuice function is called setPos which enables a player to be placed at a particular location in a Minecraft world.

It is primarily through the RasberryJuice functions setBlock and setPos that Bricklayer interacts with a Minecraft world (residing on a CanaryMod server).

How It Works

In the discussion that follows, we assume an environment where CanaryMod is up and running and your Minecraft client has been connected to the CanaryMod server.

An artifact residing in Bricklayer’s virtual space can be built (i.e., exported) to a Minecraft world residing on a CanaryMod server by simply changing the show function call (which outputs the artifact to LDD) to showMC. The showMC will cause Bricklayer to create a Python program consisting of one setPos function call, to position your avatar (i.e., player), followed by a sequence of setBlock function calls, one function call for each cell in Bricklayer’s virtual space occupied by a piece. The resulting Python program is written to a file which is then executed using a system-level command. From a conceptual standpoint, that is all there is to it. The rest is engineering. In this case, it is software engineering.

In engineering, the realization of a conceptually simple solution to a problem can often times be much more complex than initially expected. In the workplace, this can result in tension between management, whose understanding of a problem is in conceptual terms, and engineers, whose constructions must account for all of the details underlying the conceptual solution. Engineers will tell you that, when building something, the vast majority of the work revolves around details of the solution that are either not initially known or not inherently apparent at the conceptual level. This is also the case when it comes to integrating Bricklayer with Minecraft. We will not go into the nitty-gritty details here, but would like to list some of the issues that Bricklayer must address.

• Documentation
  • Documentation must be developed explaining how to install the tools necessary for integrating Bricklayer with Minecraft.
  • Documentation must be developed listing the Minecraft blocks supported. To improve readability, it is useful for this documentation to associate a name and an image (e.g., gif) with each supported block. A plan must be developed for obtaining this set of images.
• Testing
  • The Python API (mcpi) specifically assigns names to 71 Minecraft blocks. From a technical standpoint, it turns out that the setBlock function can accept codes for over 343 blocks. However, some blocks cannot be placed. After obtaining the Minecraft block list (i.e., names and codes), a series of tests was conducted to determine which blocks can be placed. It turns out, that the double plant blocks (e.g., sunflower) cannot be placed using the setBlock function. When dealing with problems of this scale (and bigger) it is extremely important to have a systematic approach to organizing tests, running tests, and checking test results.
• Requirements Gathering
  • In order for tests to produce reliable results, conditions must be created suitable for the placement of blocks (i.e., preconditions for the placement of blocks must be satisfied). For example, a melon stem must be placed on farmland and a lily pad must be placed on water. These conditions must be discovered and should be documented. It is important that the list of conditions be sound (i.e., correct) and complete (i.e., accounting for all supported blocks).
  • Through testing it has been determined that timing as well as order is important to the placement of certain kinds of blocks. More specifically, some blocks have temporal and spacial dependencies associated with them. For example, doors should be placed last (after door frames). The setBlock function only places single blocks. However, a door occupies two blocks. This causes some problems with doors in general. However, testing suggests that it is best to place the bottom block of a door before placing its top block. The sand and gravel blocks will fall if there is air below them. When creating large artifacts in a Minecraft world situations can arise where there is enough delay to cause a sand block to fall if it is placed above and before another non-air block. To address this issue, blocks should be placed from lowest to highest.
  • Use Cases
    • Bricklayer must also anticipate how it will be used to create artifacts in Minecraft. Consider a scenario where, through Bricklayer, a large complex artifact has been created in a Minecraft world. Suppose that one wants to move a large complex artifact a few blocks to the right. Simply changing coordinates and calling showMC will create a duplicate artifact. In almost all cases, such a simple process will produce unacceptable results. The correct approach is to first erase the existing artifact and then re-build it at a new location. To support this type of activity Bricklayer provides function call showAsAir. Replacing showMC with showAsAir in a Bricklayer program will cause the artifact created by the program to be constructed entirely out of air blocks. This is acceptable in most (but not all) cases. Consider the case where a building is constructed underground and the substance above the building is sand or gravel. Currently, Bricklayer does not handle such cases.
• Design
  • The most natural way to incorporate Minecraft blocks into Bricklayer is to extend the definition of the pieces that can occupy cells in Bricklayer’s virtual space. Instead of just allowing LEGO bricks to occupy cells, Minecraft blocks may also occupy cells. Thus, artifacts in the virtual space can be abstractly seen as a heterogeneous set of LEGO bricks and Minecraft blocks. This design decision has consequences for Bricklayer’s show, showMC, andshowAsAir functions. Artifacts viewed in LDD must consist exclusively of LEGO bricks and artifacts created in a Minecraft world must consist exclusively of Minecraft blocks. To satisfy this constraint a function needs to be developed that maps LEGO bricks to Minecraft blocks, and another function needs to be created that maps Minecraft blocks to LEGO bricks. The implementation of these functions must be tested (or verified) to assure that an attempt to place a LEGO brick in a Minecraft world will never be made. Similarly, a Minecraft block should never be sent to LDD. The show/showMC/showAsAir functions will use these mapping functions to translate the contents of each cell in Bricklayer’s virtual space so that the translated piece is appropriate for the tool being targeted. Since Bricklayer can create Minecraft artifacts consisting of hundreds of thousands of pieces. The efficiency of the mapping functions should be taken into account.
  • It turns out that the coordinate spaces of Bricklayer and Minecraft do not align. In a typical navigational map North corresponds to “up” on the map and East corresponds to “right” on the map. In mathematics, an xz Cartesian coordinate plane drawn on a piece of paper will typically associate North (the top of the paper) with the positive z-axis and East with the positive x-axis. Bricklayer’s coordinate system is based on this model. However, Minecraft associates North with the negative z-axis and East with the positive x-axis. Because of this, Bricklayer needs to make adjustments to coordinates so that the orientation of an artifact viewed in LDD is the same as that of Minecraft. Furthermore, users of Bricklayer should be shielded from this coordinate discrepancy to the fullest extent possible.

Bricklayer’s Minecraft-centric Functions

Known Issues and Limitations

Bricklayer currently supports 343 Minecraft blocks. However, there are problems and limitations associated with the placement of some blocks. The full range of possibilities of how blocks can be used has not yet been tested. However, the known issues and limitations discovered thus far are listed below.