FindingBlocks

There are three basic ways of getting blocks:

1. By location
2. By what you target
3. Relative to an existing block

By Location

This is pretty simple. You get a reference to the world you are in (typically received via an event) and then:

e.player.world.block_at x, y, z

Or if you have an existing org.bukkit.Location instance:

e.player.world.block_at location

By what you target

This is has two modes. In the first mode it represents what you literally see as targeted when looking at it from the client perspective. If you get a block to highlight and then call player.target_block, then you will get a reference to that block. If you try and target something which does not get the client to show the special target outline in the block, then you will still get a reference to that block assuming it is not too far away.

The second mode is to specify what sorts of block types you want to ignore. This is useful if you want to ask for the first block you can target, ignoring any trees that may be in the way.

An extra dimension not mentioned above is that you can also set a max_distance to not look too far for a target block. The most important reason for mentioning this aspect is that you may not reach a target block and get a nil result (note: this can also be true if you ignore too many block types and never find a valid block type).

Some examples:

# What you intuitively look at as a target block (first non-air block you are pointing at)
player.target_block 

# Like previous example but you will also ignore wood and leave blocks
player.target_block([:wood, :leaves, :air])

# Allow a much longer selection that the default (30)
player.target_block(:air, 80)

Relative to an existing block

Once you have a block it is simple to get blocks relative to that block. The main method is block_at. There are two parameters for this method. The first is the facing you care about. I think the values will speak for themselves: :north, :east, :south, :west, :up, :down, :north_east, :north_west, :ne, :nw, :south_east, :south_west, :se, :se, :self

The second distance parameter is also quite simple. It is the number of block away from this block you are interested in. If you omit this distance parameter it will default to 1.

Some examples:

# Go one east and up three blocks and return that block
block.block_at(:east).block_at(:up, 3)

One More Thing

Several methods allow you to just provide the block or entity you want instead of the location they are at because they implement to_loc. Methods should use to_loc when it is available.