MinecraftForge/MinecraftForge — pull request #1367 by bloodmc (2014-08-27 02:50:35+00:00)
Title: Added PlaceEvent and MultiPlaceEvent which fires before placing a block.

Before calling "ItemStack.tryPlaceItemInWorld", a recording flag is turned on for
setBlock to capture a blocksnapshot for each block that attempts to be placed.

If 1 block is captured, a "BlockEvent.PlaceEvent" is fired to notify mods.
If 2 or more blocks are captured, a "BlockEvent.PlaceEvent" is fired first with the first block
captured followed by a "BlockEvent.MultiPlaceEvent" with all captured blocks. This extra event
is required for items that have the ability to place 2 or more blocks such as a BlockBed.

If either event is cancelled, the recorded block snapshot(s), item stacksize, and item meta will
revert back to the captured snapshot(s).
If the events are not cancelled, a notification will be sent to clients and block physics will be updated.

What this means for mods is Forge will be able to capture all player block placement automatically and fire
a PlaceEvent and/or MultiPlaceEvent.
If for whatever reason your mod does not use the standard placement methods then you will need to fire the
appropriate placement events in order to notify mods/servers.

This commit also includes a new utility class called BlockSnapshot. This new class is used in conjunction with
both PlaceEvent and MultiPlaceEvent in order to record a snapshot of block space before it is altered. This
allows us to restore the block(s) if an event is cancelled. The class also provides the ability to restore a snapshot
to any location using the restoreToLocation method. This should be helpful to many mods that are looking to be able
to capture block data then restore it to back to any location required.