proposed digging api

readme.md

Proposed Digging API, first pass

event "diggingCompleted"

Fires when the block you were digging has broken.

block.isDiggable

Whether the block is diggable. This returns false for air, water, lava, etc.

bot.activateItem()

Activate the held item. This action is pressing down right-click for the item.

bot.deactivateItem()

Deactivate the held item. This action is releasing right-click for the held item.

bot.placeBlock(point, faceVector)

Place the currently equipped block.

bot.activateBlock(block)

Activate a block. Use the default right-click option for the given block (e.g. open chests, furnaces, change delay of a repeater, etc).

bot.startDigging(block)

Begin digging into a block with the currently equipped item. When you finally break through the block, you get a "diggingCompleted" event. Until the 2nd pass is implemented, there is no way to stop digging.

bot.targetDigBlock

If you are currently digging, this is the Block that you are digging. If you are not currently digging, this is null.

2nd pass. Add ability to predict how long things will take to dig so we can add these api functions:

event "diggingAborted"

Fires when digging has been cancelled.

bot.stopDigging()

Stops digging.

• Separate events for aborted/finished digging would be nicer I think.
• bedrock is 'diggable' but not 'breakable'. Technically clients CAN dig bedrock.

New things to take into account:

• You can place blocks against activateable blocks when shift is held (bot.canPlaceBlock should take an optional shiftHeld argument).
  • Need to investigate whether it's possible to place blocks against activateable blocks when shift is NOT held.
• Mouse 3 (middle mouse/scroll wheel button) works as a pick block to select the targeted block if it is on the quickbar (this is also relevant to inventory).

More info about controls: http://www.minecraftwiki.net/wiki/Controls#Computer

Pick block is a client side nicety that mineflayer willfully ignores. If someone wants this they can build it as a 3rd party plugin.

I removed a bunch of legacy documentation - we will simply lift many of those restrictions.

Same as holding an item and right clicking in the game.

Do you mean literally identical, as in if I'm holding shift holding cobblestone targeting a chest, it will put a cobblestone block there?

The intent is that if you want to place a block, you use placeBlock, but if you want to fire a bow or eat a sandwich you use activateItem. Do you have a suggested change to make this API simpler and/or easier to understand?

Suggested changes just to wording of a few things (see my fork: https://gist.github.com/4528503).

How do we intend to handle the bot using his fists to punch obsidian, when a player comes in to mine that obsidian with a Diamond Pickaxe (finishing off the block quicker than the bot)? Would this be a diggingCompleted? Does one method of digging (first or second pass) work better or have any issues with this?

it would probably be a digging completed either way.