Assignment 2, CSC102, Spring 2012

1 Guidelines

1.1 Contracts & Test Cases

For this and all remaining assignments, every method you develop must come with the following things:

• A commented header line that expresses the result of the function in terms of its inputs, written in English. Be as precise as you can within the space of a line or two. When implementing a method on mixed data, this comment only need appear in the interface.

• Test cases. When a problem asks you to develop data (classes and interfaces), provide examples of the data. When a problem asks you to develop a method, provide assertEquals tests. If the method is on a piece of mixed data, be sure to provide test cases for all of the union’s variants.

2 Background

This assignment is "related to Minecraft." That is, you’ll be developing a program that can be used as a plugin for Minecraft. I’m going to briefly describe the game, but I want to emphasize that this programming project does not require you to buy the game or to play the game or even to understand the game, much.

Minecraft is a "sandbox" game; it takes a first-person perspective, and presents a simple but extremely large world consisting primarily of large blocks. From a distance, it looks nice :)

Playing the game involves wandering around in this world, digging holes (hence the "mine-"), and building structures. If you google for minecraft screenshots, you will see many elaborate castles and buildings. The game also involves constructing or finding shelter before nightfall, when monsters appear.

Minecraft is written in Java. This means that it’s possible to modify, or "mod", the game, by writing Java code. More specifically, the compiled minecraft application can be "de-compiled", modified, and the re-compiled. If that sounds difficult... it is! Fortunately, it’s not necessary, because several folks have done the hard work for you. The most well-known project in this arena is "Bukkit". They provide a library that you can compile and link your code against, and a modified version of the Minecraft server (CraftBukkit) that makes it easy to add plugins. The rest of this assignment is going to focus on the process of building the plugin, and totally ignore the issue of deploying it. For more information on running a CraftBukkit server and trying out your plugin, see the CraftBukkit developer wiki, at

http://wiki.bukkit.org/Portal:Developers

3 Assignment

In this assignment, you will be implementing a number of simple methods to create a Minecraft "plugin" that can create rectangular structures in the game.

4 Getting Started

The first thing you’ll need is to create a project, download the "Bukkit" interface library, and get it linked to your project. The easiest way to do this is to follow the steps outlined in section 4 of the "Plugin Tutorial", online at

http://wiki.bukkit.org/Plugin_Tutorial

This will walk you through the creation of a simple plugin project. Use the name "edu.calpoly.cpe102sp12" for your package name.

Stop before you get to the section labeled "onEnable() and onDisable()". Your plugin class does not need to contain any fields or methods, including a constructor.

5 The Coordinate System

Minecraft uses a standard right-handed coordinate system. In particular, the X axis points east, the Y axis points up, and the Z axis points south. Just to give you a sense of scale, the world is (currently) of height 256, so that the maximum possible value of Y is 255. Sea Level is at approximately y = 64, so areas below this are either underwater or in caves.

6 Rectangular Prisms

Define a RectangularPrism class that has an X, a Y, and a Z dimension, and an X, Y, and Z location, denoting the center of the prism. All should be represented as integers. Do this just as you would in a lab; the constructor should accept these six arguments.

Create a Testing class, that contains a test method that creates at least three examples of these prisms. Create test cases for the following two methods in the Testing class.

Develop the scale method, that accepts a double ’s’ and returns a new rectangular prism that has the same center but whose size is scaled by s. Round the dimensions in order to insure that they are still integers. Be sure not to alter the original prism.

Develop the translate method, that accepts integers dx, dy, and dz, and returns a new prism that is translated by the given amounts.

7 Rendering

To make it possible to transform these prisms into actual Minecraft structures, we need some "glue" code. First off, we’ll need a "proxy" world to model the Minecraft world, so that you (and I) can test your code independently of the full server.

Define the SimpleWorld interface, and the TestingWorld class that implements it. A TestingWorld should have an xdim, a ydim, and a zdim dimension as fields and constructor arguments, and should also contain a mutable array of length xdim * ydim * zdim, of type Material. The constructor should create this array. (The Material type is defined by the library you’re linking against.) The array should initially be filled with air, defined by the library you’re using as Material.AIR .

This array will be used to represent the blocks in the test world. The first xdim cells will represent the blocks at coordinates (0,0,0) up to (xdim,0,0), the next xdim cells will represent the blocks at coordinates (0,1,0) up to (xdim,1,0), and so forth.

Now, develop two methods on this class and interface: the getBlockType method, that accepts an x, a y, and a z coordinate and returns the element in the array that corresponds to the given coordinates, and a matching setBlockType method, that accepts three coordinates and a Material, and sets the corresponding element of the array to be the given material. These methods are part of the testing framework, and you don’t need to develop tests for them, though you might want to. Calling either method with an illegal dimension—for instance, an x coordinate that is smaller than zero or greater than xdim—should "throw an error", as described below.

The materials are defined by the library. There are quite a number of materials, but for testing purposes, it will be fine to limit yourself to Material.AIR, Material.STONE, and Material.DIRT. You can look up more, if you’re interested.

With these defined, you can define the render method on a RectangularPrism, that accepts a SimpleWorld and a Material, and sets every block in the rectangular prism to that material by calling the SimpleWorld’s setBlockType method repeatedly. In the case of odd-sized prisms, round toward the smaller coordinate at both edges. So, for instance, a rectangular prism with an X dimension of 5 centered on a point with the X coordinate of 32 should include the X coordinates 29, 30, 31, 32, and 33.

8 Signaling Errors

Java has a lovely exception mechanism; for now, we’re just interested in the ability to signal errors. The easiest way to do this is to "throw" a new "RuntimeException".

So, for instance, you might write

throw new RuntimeException("Expected x coordinate between 0 and 20, got 35.");

You are not responsible for testing error-signalling behavior.

9 Linking it to Minecraft

If you want to see your prisms in the game of Minecraft, you’ll need a definition for the plugin that handles a particular command and calls your render method. I’ll provide this code.... a bit later.

10 Submitting your work

All of your work on this project should be done with your team, including your submission. One of your team should submit, using Web-CAT, and provide the usernames of the other team members at submit time in the box provided.

11 Errors in the Assignment

I bet you can find some errors in this assignment. When you do, let me know about them!