Navigation

Vocabulary

meter - a block is 1 meter cubed, or 1x1x1.

Enums

class mf.EntityType
Player
Mob
Pickup
class mf.ItemType

The id of blocks and items. See the output of examples/reflect.js for a full listing of names.

class mf.Face

Which side of a block, if any.

NoDirection
NegativeX

North

PositiveX

South

NegativeY

Down

PositiveY

Up

NegativeZ

East

PositiveZ

West

class mf.MobType
Creeper
Skeleton
Spider
GiantZombie
Zombie
Slime
Ghast
ZombiePigman
Enderman
CaveSpider
Silverfish
Blaze
MagmaCube
EnderDragon
Pig
Sheep
Cow
Chicken
Squid
Wolf
Snowman
Villager
class mf.StoppedDiggingReason
BlockBroken
Aborted
class mf.Control

Represents an input action as if you were pressing buttons on a keyboard.

Forward
Back
Left
Right
Jump
Crouch

TODO (not hooked up)

DiscardItem

TODO (not hooked up)

class mf.AnimationType
NoAnimation
SwingArm
Damage
Crouch
Uncrouch
class mf.WindowType
None
Inventory
Chest
Workbench
Furnace
Dispenser
class mf.MouseButton

For sending window clicks.

Left
Right
class mf.Dimension
Normal
Nether

Classes

class mf.Point(x, y, z)

Represents a 3D coordinate/location in meters.

Example:

var point = new mf.Point(0, 0, 0);
x

Number, south

y

Number, up

z

Number, west

floored()
Return type:Point
Returns:A new point with each coordinate rounded down to the nearest integer.
offset(dx, dy, dz)
Return type:

Point
Returns:

A new Point offset by the amount specified.
Parameters:
  • dx (Number) – How much to offset x.
  • dy (Number) – How much to offset y.
  • dz (Number) – How much to offset z.
plus(other)
Return type:Point
Returns:A new point with each term offset by other.
Parameters:other (mf.Point) – The point to add.
minus(other)
Return type:Point
Returns:A new point with each term subtracted by other.
Parameters:other (mf.Point) – The point to subtract.
scaled(scalar)
Return type:Point
Returns:A new point with each term multiplied by scalar.
Parameters:other (Number) – The number to multiply by.
abs()
Return type:Point
Returns:A new point with each term the absolute value of its former value.
distanceTo(other)
Return type:Number
Returns:The Euclidean distance from the point to other.
Parameters:other (mf.Point) – The point to compute the distance to.
equals(other)
Return type:Boolean
Returns:Whether or not the points are equal.
Parameters:other (mf.Point) – The point to check.
toString()
Return type:String
Returns:The point represented in text form.
clone()
Return type:Point
Returns:A new point which is a copy of the original.
class mf.Entity

Contains a snapshot of an entity’s state.

entity_id

Number, the id of this entity.

type

mf.EntityType

position

mf.Point, the center of the bottom of of the entity.

velocity

mf.Point, the entity’s velocity in meters per second squared.

yaw

Number, range [0, 2pi], rotation around vertical axis. 0 is -z (east). pi/2 is -x (north), etc.

pitch

Number, range [-pi/2, pi/2], 0 is parallel to the ground. pi/2 is up. -pi/2 is down.

on_ground

Boolean, true if you are not free-falling.

height

Number, distance from ground to eyes. 0 for non-humanoid entities.

Additional properties when type is mf.EntityType.Player:

username

String

held_item

mf.ItemType, the item the player is holding in their hand

effects

Object, maps mf.StatusEffectType to mf.StatusEffect

Additional properties when type is mf.EntityType.Mob:

mob_type

mf.MobType

Additional properties when type is mf.EntityType.Pickup:

item

mf.Item

class mf.Item(type[, count[, metadata]])

Represents an item or stack of items.

type

mf.ItemType

count

Number, defaults to 1

metadata

Number, defaults to 0

Examples:

var item1 = new mf.Item(mf.ItemType.Dirt, 64)
var item2 = new mf.Item(mf.ItemType.StoneSword)
class mf.Block(type[, metadata[, light[, sky_light]]])

Represents a block placed in the world

type

mf.ItemType

metadata

Number, defaults to 0

light

Number, defaults to 0, light from local sources (not the sky)

sky_light

Number, defaults to 0, potential light from sky if it was daytime

class mf.HealthStatus(health, food, food_saturation)

Represents the health and food status of the player

health

Number, in the range [0, 20] representing the number of half-hearts

food

Number, in the range [0, 20] representing the number of half-turkey-legs

food_saturation

Number, currently always 0

class mf.StatusEffect(effect_id, amplifier, start_timestamp, duration_milliseconds)

Represents the health and food status of the player

effect_id

mf.StatusEffectType

amplifier

Number, always 0?

start_timestamp

Number, see mf.currentTimestamp()

duration_milliseconds

Number

Methods

mf.include(path)
Parameters:path (String) – The filepath to the script including the extension.

Runs a script with a path relative to the current script. Modularize your bot by using this function to import components. This method will not run a script twice.

mf.setTimeout(func, time)

Call a function later.

Parameters:
  • func (Function) – The function that you want to execute later.
  • time (Number) – The amount of milliseconds you want to wait before executing func.
Returns:

an ID which you can use to cancel the timeout.
Return type:

Number
mf.clearTimeout(id)

Stop a timeout that is in progress

Parameters:id (Number) – The ID which you got from setTimeout().
mf.setInterval(func, time)

Execute a function on a set internal.

Parameters:
  • func (Function) – The function that you want to execute every time milliseconds.
  • time (Number) – The interval in milliseconds you want to wait between executing func.
mf.clearInterval(id)

Stop an interval that is in progress

Parameters:id (Number) – The ID which you got from setInterval().
mf.currentTimestamp()

Returns the number of milliseconds since some arbitrary fixed event in the past.

mf.debug(line)

Prints a line of text to stderr. Useful for debugging.

Parameters:line (String) –
mf.print(string)

Prints a string to stdout. Does not put a newline character at the end. :param String string:

mf.readFile(path)

Reads a text file and returns the contents as a string. Returns undefined if the file cannot be opened.

Parameters:path (String) – The path to the file.
Return type:String or undefined
Returns:Contents of the file as a String.
mf.writeFile(path, contents)

Writes a text file with the specified contents.

Parameters:
  • path (String) – The path to the file
  • contents (String) –
mf.args()
Return type:Array of Strings
Returns:the script’s arguments from the command line invocation.
mf.chat(message)

Sends a publicly broadcast chat message. Breaks up big messages into multiple chat messages as necessary. If message begins with “/tell <username> ”, then all split messages will be whispered as well.

Parameters:message (String) –
mf.exit(return_code)

Disconnects from server and exits the program.

Parameters:return_code (Number) – Optional. Defaults to 0.
mf.itemStackHeight(item)

Gets the number of items you can stack together.

Parameters:item (mf.ItemType) – The ID of the item you want to check the stack height of.
Returns:The number of items of type item you can stack together, or -1 if that item doesn’t exist.
Return type:Number
mf.isPhysical(block_type)

Returns whether the block type has any physical presence with respect to physics. This is false for air, flowers, torches, etc.

Example:

if (mf.isPhysical(mf.blockAt(some_point).type)) {
    // water physics
}
Parameters:block_type (mf.ItemType) –
Return type:Boolean
mf.isSafe(block_type)

Returns whether the block type is non-physical and safe to stand in. This returns false for lava, fire, and everything that isPhysical() returns true for.

Parameters:block_type (mf.ItemType) –
Return type:Boolean
mf.isDiggable(block_type)

Returns whether the block type is diggable. This returns false for air, bedrock, water, lava, etc.

Parameters:block_type (mf.ItemType) –
Return type:Boolean
mf.healthStatus()
Return type:HealthStatus
Returns:A snapshot of your current health and food status
mf.blockAt(point)

Returns the block at the absolute location in the world. If isBlockLoaded() returns false for the point, this function will return some kind of Air.

Parameters:point (mf.Point) – Coordinates do not need to be rounded.
Return type:Block
mf.isBlockLoaded(point)
Parameters:point (Number) – Coordinates do not need to be rounded.
Return type:Boolean
Returns:whether the map is loaded at the specified point.
mf.signTextAt(point)

Returns the text of the sign at the specified location, or undefined if the block at the location is not a sign. Lines are separated by ‘n’.

Parameters:point (mf.Point) – The location of the sign
Return type:String or undefined
mf.canPlaceBlock(point, face)

Returns whether or not you’re able to place your currently equipped item on the face of the block at point. Takes into account distance, whether something is in your way, whether the target block is activatable, and what you’re equipped with.

Parameters:
  • point (mf.Point) – The location of the block you want to check.
  • face (mf.Face) – The face of the block you want to attach to.
mf.self()

Returns a snapshot of your state in the world as an entity. Modifying the object does nothing.

Return type:Entity
mf.setControlState(control, state)

Sets the input state of a control. Use this to move around, jump, and place and activate blocks. It is as if you are virtually pressing keys on a keyboard. Your actions will be bound by the physics engine, (unless you use the mf.hax functions).

Parameters:
  • control (mf.Control) –
  • state (Boolean) – Whether or not you are activating this control. E.g. whether or not the virtual button is held down.
mf.clearControlStates()

Sets all control states to false.

mf.lookAt(point[, force])

Looks at the given point specified in absolute coordinates. See also mf.look().

Parameters:
  • point (mf.Point) –
  • force (Boolean) – If present and true, skips the smooth server-side transition. Specify this to true if you need the server to know exactly where you are looking, such as for dropping items or shooting arrows. This is not needed for client-side calculation such as walking direction.
mf.respawn()

Call this when you’re dead to respawn.

mf.activateItem()

Eat, shoot, throw, etc. your currently equipped item. Throws an exception if your currently equipped item can’t be activated.

mf.dimension()

The dimension you currently occupy.

Return type:Dimension
mf.onlinePlayers()

An object containing all the online players and their pings. Includes yourself.

Return type:Object mapping names to Number pings in milliseconds.

Cheating methods

hax.placeBlock(block, face)

Place the currently equipped block. If the block at point is a chest, furnace, workbench, etc, this will throw an exception. See activateBlock(). If the equipped item is food, this will throw an exception. See setControlState(). This method is considered cheating. See description of canPlaceBlock() for an example of how to place blocks without cheating.

Parameters:
  • block (mf.Point) – The coordinates of the block that you want to place the block on.
  • face (mf.Face) – Which side of the block you want to place the block on.
hax.activateBlock(block)

Same as right-clicking. This is for chests, furnaces, note blocks, etc. Throws an exception if the block is not activatable. This method is considered cheating. See description of canPlaceBlock() for an example of how to activate blocks without cheating.

Parameters:block (mf.Point) – The coordinates of the block that you want to activate
hax.setPosition(point)

Instantly moves you to the position specified. NOTE: Your movement may be rejected by the server. This can happen if you try to go through a wall.

Parameters:point (mf.Point) –
hax.setGravityEnabled(value)

Turns on/off gravity. When gravity is off, you will not take fall damage.

Parameters:value (Boolean) –
hax.setJesusModeEnabled(value)

Pretend that water is solid.

Parameters:value (Boolean) –
mf.attackEntity(entity_id)

Sends a single attack message to the server.

Parameters:entity_id (Number) –
mf.entity(entity_id)
Parameters:entity_id (Number) –
Return type:mf.Entity or undefined:
Returns:a snapshot of the entity with the given entity id or undefined if the entity id cannot be found. Modifying the object does nothing.
mf.startDigging(point)

Begin digging into a block with the currently equipped item. When you finally break through the block, or you are interrupted for any reason, you will get an onStoppedDigging() event.

Parameters:point (mf.Point) – The location of the block to dig.
mf.stopDigging()

Stops digging.

mf.look(yaw, pitch)

Looks in a direction.

Parameters:
  • yaw (Number) – The number of radians to rotate around the vertical axis, starting from due east. Counter clockwise.
  • pitch (Number) – Number of radians to point up or down. 0 means straight forward. pi / 2 means straight up. -pi / 2 means straight down.
mf.selectedEquipSlot()
Returns:The slot id [0-8] of the selected equipment.

See the diagrams in clickUniqueSlot().

mf.selectEquipSlot(slot)

Selects an equipment slot.

Parameters:slot (Number) – The id of the slot [0-8] you wish to select.

See the diagrams in clickUniqueSlot().

mf.clickInventorySlot(slot, button)

Simulates clicking the mouse button as with the real client. Make sure you use openInventoryWindow() and get the onWindowOpened() event before using this function.

Parameters:
  • slot (Number) – The slot id you wish to click on.
  • button (mf.MouseButton) – Which mouse button you wish to simulate clicking with.

See the diagrams in clickUniqueSlot().

mf.clickUniqueSlot(slot, button)

Simulates clicking the mouse button as with the real client. Make sure you get the onWindowOpened() event with the correct window id before using this function.

Parameters:
  • slot (Number) – The slot id you wish to click on.
  • button (mf.MouseButton) – Which mouse button you wish to simulate clicking with.

The slot ids are as follows:

_images/container-slots.png

Double chest slot ids. Single chest is the top half only.

_images/furnace-slots.png

Furnace slot ids.

_images/trap-slots.png

Dispenser slot ids.

_images/crafting-slots.png

Crafting Table slot ids.

_images/inventory-slots.png

Inventory slot ids.

mf.clickOutsideWindow(button)

Simulates clicking outside of the open window.

Parameters:button (mf.MouseButton) – Which mouse button to simulate clicking with.
mf.openInventoryWindow()

Opens the inventory window. Will cause an onWindowOpened() event.

mf.closeWindow()

Closes the open window.

mf.inventoryItem(slot)
Returns:The item in slot.
Return type:mf.Item
Parameters:slot (Number) – The slot id to return the item for.

See the diagrams in clickUniqueSlot().

mf.uniqueWindowItem(slot)
Returns:The item in slot.
Return type:Item

See the diagrams in clickUniqueSlot().

mf.timeOfDay()

Tells what time it is, also known as where the sun or moon is in the sky.

Return type:Number
Returns:The number of real life seconds since dawn (6:00am). This ranges from 0 to 1200 since a day is 20 minutes.

Events

Fill in the ... part of the function. See examples for more information.

mf.onConnected(function() {...})

Called when the bot successfully logs into a server.

mf.onChat(function(user, message) {...})

Called when the bot hears a publicly broadcast chat message.

Parameters:
  • user (String) – The username of the person sending the message.
  • message (String) – The content of the message.
mf.onNonSpokenChat(function(message) {...})

Called when a chat is received that was no spoken by a player. This includes player joined messages, teleporting notifications, etc.

Parameters:message (String) – All color codes will be removed
mf.onTimeUpdated(function(seconds) {...})

Called every second. See timeOfDay().

Parameters:seconds (Number) – Number of seconds since dawn.
mf.onChunkUpdated(function(start, size) {...})

Called when blocks are updated. Updated region is a rectangular solid even if not all of the blocks in the region have actually changed.

Parameters:
  • start (mf.Point) – The absolute position of the min corner of the region.
  • size (mf.Point) – The size of the region.
mf.onSignUpdated(function(location, text) {...})

Called when a sign is discovered or destroyed or when a sign’s text changes.

Parameters:
  • location (mf.Point) – The location of the sign
  • text (String) – The new text of the sign or undefined if the sign was destroyed
mf.onSpawn(function(dimension) {...})

Called when you spawn. Happens after connecting and after respawning after death.

Parameters:world (mf.Dimension) – Either mf.Dimension.Normal or mf.Dimension.Nether.
mf.onSelfMoved(function() {...})

Called when you move. See also self().

mf.onHealthStatusChanged(function() {...})

Called when your health/food status changes. See also healthStatus().

mf.onDeath(function() {...})

Called when you die.

mf.onEntitySpawned(function(entity) {...})

Called when an entity is discovered. This can happen when an entity is created or when it comes into view.

Parameters:entity (mf.Entity) –
mf.onEntityDespawned(function(entity) {...})

Called when an entity vanishes from known existence. This can happen when an entity is destroyed or when it goes out of view.

Parameters:entity (mf.Entity) –
mf.onEntityMoved(function(entity) {...})

Called when an entity moves or in some other way changes state.

Parameters:entity (mf.Entity) –
mf.onAnimation(function(entity, animation_type) {...})

Called when an entity animates

Parameters:
mf.onEntityEffect(function(entity, effect) {...})

Called when an effect is observerd on an entity, possibly yourself.

Parameters:
mf.onRemoveEntityEffect(function(entity, effect) {...})

Called when an effect is observerd to have stopped on an entity, possibly yourself.

TODO: Issue #37: this callback is unreliable.

Parameters:
mf.onStoppedDigging(function(reason) {...})

Called when you have stopped digging for some reason.

Parameters:reason (mf.StoppedDiggingReason) –
mf.onEquippedItemChanged(function() {...})

Called when what you are currently equipped with changes. For example, if your pickaxe breaks or you eat food. See also equippedItem(). TODO: equippedItem is not documented

mf.onInventoryUpdated(function() {...})

Called when anything in your inventory changes. See also inventoryItem().

mf.onWindowOpened(function(window_type) {...})

Called when you can begin messing with a chest or your inventory.

Parameters:window_type (mf.WindowType) –
mf.onStdinLine(function(line) {...})

Called when a line of stardard input is typed in the console.

Parameters:line (String) –
mf.removeHandler(event_registrar, handler)

Removes the handler from the event.

Example:

mf.onChat(function handleChat(username, message) {
    mf.debug("got first chat");
    mf.removeHandler(mf.onChat, handleChat);
});
Parameters:
  • event_registrar (Object) – One of mf.on*
  • handler (Function) – function registered previously with the event

Table Of Contents

Previous topic

Welcome to mineflayer’s documentation!

This Page

Navigation

© Copyright 2011, Andrew Kelley, Josh Wolfe, Casey Kuball. Created using Sphinx 1.1.3.