Importing modules

In the previous python in minecraft blog we created a program to construct an east-west tunnel. This is a useful program which we might want to use often. We can put the program into a function and save the function in a module so it can be used by other programs. We will call the function “buildEastTunnel()”. The module name will be just the name of the file, which in this case we will call “tunnel.py”. Then whenever we want to build a tunnel running east west, we can import the module just like we have been importing mcpi.minecraft and mcpi.block.

There are several ways to import functions. The simplest method imports the module but not the function name. We still need to tell python to look in that module when calling the function

import tunnel
tunnel.buildEastTunnel()

If you want to give the module a better name you can use “as” to assign a new name. This is what we do when importing mcpi.minecraft as minecraft.

import tunnel as mole
mole.buildEastTunnel()

If you want to use the function without qualifying it with the module name each time, you can import the function explicitly from the module.

from tunnel import buildEastTunnel
buildEastTunnel()

Function parameters

Now calling buildEastTunnel() as it is currently written will always construct a tunnel in the same place, x = -400 to -200, y = 72 at each end, z = 244. However, if we design the function to take parameters then when we call the function we can specify where the tunnel is built.

# tunnel.py
def buildEastTunnel(mc, x1, x2, y1, y2, z):
    """Builds an east-west tunnel (in the x direction)"""
    # rest of function ...

# example10.py
import mcpi.minecraft as minecraft
from tunnel import buildEastTunnel
mc = minecraft.Minecraft.create()
buildEastTunnel(mc, 0, 200, 75, 75, 233)

This example passes the mc object to the function so it knows which minecraft server to build the tunnel in. Then it gets the x, y and z coordinates at each end of the tunnel. Because the tunnel is running east-west there is only one z value required. Our code is designed to go from xmin to xmax but someone calling our function might put the higher value of x first and the lower value second or vice versa. We can take advantage of python’s ability to assign several variables at once to ensure xmin is less than xmax.

def buildEastTunnel(mc, x1, x2, y1, y2, z):
    """Builds an east-west tunnel (in the x direction)"""
    if x1 < x2:
        xmin, yatxmin, xmax, yatxmax = x1, y1, x2, y2
    else:
        xmin, yatxmin, xmax, yatxmax = x2, y2, x1, y1
    # rest of function ...

When designing a function to take parameters, it is possible to specify some parameters as “required” and other parameters as “optional”. Optional parameters need to be given a default value. In our example it would be useful for the y values to use ground level if it is not supplied. “Required” parameters have to come before “optional” parameters so the parameters list should now be (mc, x1, x2, z, y1, y2).

def buildEastTunnel(mc, x1, x2, z, y1=None, y2=None):
    """Builds an east-west tunnel (in the x direction)"""
    if x1 < x2:
        xmin, yatxmin, xmax, yatxmax = x1, y1, x2, y2
    else:
        xmin, yatxmin, xmax, yatxmax = x2, y2, x1, y1
    if yatxmin == None:
        yatxmin = getGroundHeight(mc, xmin, z)
    if yatxmax == None:
        yatxmax = getGroundHeight(mc, xmax, z)
    # rest of function ...

Finding ground height

We are calling a function getGroundHeight(mc,x,z) which we haven’t written yet. In mcpi.minecraft is a function mc.getHeight(x,z) which finds the highest block which is not air at x and z coordinates. Unfortunately that block will often be a tree or sapling. Here is a function which corrects mc.getHeight(x,z) for trees. It makes use of the mc.getBlock(x,y,z) function which returns the id of the block at those coordinates.

def getGroundHeight(mc, x, z):
    """finds heighest non air block which is also not a tree or sapling"""
    LEAVES2 = block.Block(161)
    y = mc.getHeight(x, z)
    while mc.getBlock(x, y, z) in (block.AIR.id, block.LEAVES.id, block.WOOD.id, LEAVES2.id, block.SAPLING.id):
        y -= 1
    return y