Bukkit/Bukkit — pull request #1059 by desht (2014-04-29 22:20:04+00:00)
Title: Add API for improved block targeting methods.  Adds BUKKIT-5581

#### [B+C] Improved LivingEntity#getTargetBlock() and related methods. Adds BUKKIT-5581

##### The Issue:
While the current system for getting the block targeted by an entity works, there are several significant improvements to be made:

* The current methods are deprecated due to the use of magic numbers; a Set containing raw block ids to be considered transparent. In addition, this system provides poor flexibility; it should be possible to use criteria other than the block ID (or material) to determine transparency.
* The current methods do not work properly when the player is targeting a block behind another block with a smaller hitbox. E.g. where a sign is attached to wall, player.getTargetBlock() will always return the sign, even if the player is targeting the wall behind the sign.
* The current methods return the targeted block (mostly; see above), but don't say which block face was targeted, or the precise location on the block where the crosshairs are.

##### Justification for this PR:
This PR adds new methods to resolve all of the above issues.

##### PR Breakdown:
The following changes are made:

* Add new BlockTargetResult class. This simple class aggregates the information returned by the new targeting methods: the targeted block, the targeted block face, and the precise targeted location.
* Add new BlockTransparencyFilter interface. This functional interface has one method: ``boolean isTransparent(Block)``. The isTransparent() method implementation will be called by the new targeting methods and should return true if the given block is to be considered transparent, false otherwise.
* Add ``Vector[] getHitbox()`` method to the Block interface. This returns a pair of Vector objects representing opposite corners of the block's hitbox (which may be significantly smaller than the block's full 1x1x1 volume). This new method is used by the targeting methods to fix the hitbox problem mentioned above, but it's possible that plugins may also find this information useful. If this method is deemed unsuitable for addition to the API, it can be withdrawn.
* Add three new methods to LivingEntity: ``public List getLineOfSight(BlockTransparencyFilter filter, int maxDistance, boolean useHitBoxes)``, ``public BlockTargetResult getTargetBlock(BlockTransparencyFilter filter, int maxDistance, boolean useHitBoxes)``, and ``public List getLastTwoTargetBlocks(BlockTransparencyFilter filter, int maxDistance, boolean useHitBoxes)`` - these methods are intended to supercede their old equivalents which take a Set.

##### Testing Results and Materials:
A test plugin has been created.

Source: https://github.com/desht/testplugin
Binary: [will add a link shortly]

Instructions for use:

* For all tests, air, glass and white stained glass will be considered transparent (note: only white stained glass, not other colours - the old API couldn't do that!)
* Look at any block and type /target. Messages will be printed to the console display detail about the targeted block as returned by the new ``public BlockTargetResult getTargetBlock(BlockTransparencyFilter filter, int maxDistance, boolean useHitBoxes)`` method.
* With a bone in hand, right clicking while looking at any block (from any distance) will do the same as above, using ``public BlockTargetResult getTargetBlock(BlockTransparencyFilter filter, int maxDistance, boolean useHitBoxes)`
* With a bone in hand, left clicking will call ``public List getLastTwoTargetBlocks(BlockTransparencyFilter filter, int maxDistance, boolean useHitBoxes)`` and display detail for both blocks to the console.
* If the player is sneaking, hit boxes will be ignored (behaving more like the old methods)
* With a blaze rod in hand, left clicking any block will display the block's hitbox information to the console.

##### Relevant PR(s):

CB-#### - https://github.com/Bukkit/CraftBukkit/pull/#### - Implementation of new API
[will add this shortly]

##### JIRA Ticket:
BUKKIT-5581 - https://bukkit.atlassian.net/browse/BUKKIT-5581