This is a reference of Minecraft Python API Library, which is supported on Minecraft: Pi edition and the PC version using the RaspberryJuice plugin.

似乎缺少生物相关的api？难道生物也是block？

pip install mcpi

一、代码结构

minecraft.py

Class Minecraft - main class for connecting and interacting with the game

Class camera - changing camera angle and postion

Class player - getting and changing the players position and setting

Class entity - getting and changing entities position and setting

Class events - retreiving events which have occured in the game

block.py

Class Block - definition of a block, specifically its type

event.py

Class BlockEvent - definition of a block event, specifically what event, what block and what player

vec3.py

Class Vec3 - generic class for managing a 3 dimension vector (i.e. x,y,z)

connection.py - internal module used by the api

util.py - internal module used by the api

Compatability

Not all functions and block types are available on all version of the api, by each function you will see a logo which shows whether that function is available:

二、API 明细

import mcpi.minecraft as minecraft

import mcpi.block as block

1.Minecraft

"Main class for interacting with the Minecraft world, includes functions for creating a connection, modifying players and blocks and capturing events"

.create(address = "localhost", port = 4711)

"Create connection to Minecraft (address, port) => Minecraft object"

mc = minecraft.Minecraft.create() #use default address and port

mc = minecraft.Minecraft.create("192.168.1.1", 4711) #specify ip address and port

.getBlock(x,y,z)

"Get block (x,y,z) => id:int"

blockType = mc.getBlock(0,0,0) #retrieves the block type for the block at 0,0,0

.getBlocks(x0,y0,z0,x1,y1,z1)

"Get a cuboid of blocks (x0,y0,z0,x1,y1,z1) => [id:int]"

blocks = mc.getBlocks(-1,-1,-1,1,1,1) #get the block id's in a cuboid

for block in blocks:

print block

.getBlockWithData(x,y,z)

"Get block with data (x,y,z) => Block"

blockObj = mc.getBlockWithData(0,0,0) #retrieves a block object for the block at 0,0,0

.setBlock(x,y,z)

"Set block (x,y,z,id,[data])"

mc.setBlock(0,0,0,block.DIRT.id) #sets a block at an x, y, z co-ordinate to a particular type

mc.setblock(0,0,0,block.WOOD.id, 1) #sets a block to a particular type and 'subtype'

.setBlocks(x0,y0,z0,x1,y1,z1,blockType, blockData)

"Set a cuboid of blocks (x0,y0,z0,x1,y1,z1,id,[data])"

mc.setBlocks(-1, -1, -1, 1, 1, 1, block.STONE.id) #sets many blocks at a time, filling the gap between 2 sets of x, y, z co-ordinates

.getHeight(x,z)

"Get the height of the world (x,z) => int"

y = mc.getHeight(0,0) #find the y (vertical) of an x, z co-ordinate which represents the 'highest' (non-air) block

.getPlayerEntityIds()

"Get the entity ids of the connected players => [id:int]"

entityIds = mc.getPlayerEntityIds() #get the entity id's of the players connected to the game

for entityId in entityIds:

print entityId

.getPlayerEntityId(playerName)

"Get the entity id for a named player => [id:int]"

entityId = mc.getPlayerEntityId("martinohanlon") #get the entity id of a name player 'martinohanlon'

print entityId

.saveCheckpoint()

"Save a checkpoint that can be used for restoring the world"

Available on Minecraft: Pi Edition

mc.saveCheckpoint()

.restoreCheckpoint()

"Restore the world state to the checkpoint"

Available on Minecraft: Pi Edition

mc.restoreCheckpoint()

.postToChat(message)

"Post a message to the game chat"

mc.postToChat("Hello Minecraft World") #write 'Hello Minecraft World' to the chat window

.setting(setting, status)

"Set a world setting (setting, status). keys: world_immutable, nametags_visible"

Available on Minecraft: Pi Edition

mc.setting("world_immutable", True) #change world immutable to True

mc.setting("nametags_visible", False) #change nametags_visible setting to False

2.Minecraft.player

.getPos()

"Gets the player's position in the world as a Vec3 of floats (decimal numbers), if the player is in the middle of a block x.5 is returned"

playerPos = mc.player.getPos() #get players position as floats

.setPos(x,y,z)

"Moves the player to a position in the world by passing co-ordinates ([x,y,z])"

mc.player.setPos(0.0,0.0,0.0) #set the players position as floats

.getTilePos()

"Gets the position of the 'tile' the player is currently on."

playerTile = mc.player.getTilePos() #get the position of the tile the players is on

.setTilePos(x,y,z)

"Move the player to a tile position in the world by passing co-ordinates ([x,y,z])"

mc.player.setTilePos(0,0,0) #set the position of the tile the player is on

.setting(setting, status)

"Set a player setting (setting, status). keys: autojump"

Available on Minecraft: Pi Edition

mc.player.setting("autojump", True) #change the autojump setting to True

.getRotation()

"Get the rotational angle(旋转角度-水平) (0 to 360) for the player => [angle:float]"

angle = mc.player.getRotation() #get the rotation of the player

print angle

.getPitch()

"Get the pitch angle(俯仰角度-垂直) (-90 to 90) for the player => [pitch:float]"

pitch = mc.player.getPitch() #get the pitch for the player

print pitch

.getDirection()

"Get unit vector of x,y,z for the player's direction => [Vec3]"

direction = mc.player.getDirection() #get the player's direction

print direction

3.Minecraft.entity

The entity functions are used in conjunction with the .getPlayerEntityIds() function to interact with the entity (or players) 玩家 in a game. Entity functions are useful for multiplayer games.

entity - players - 玩家， mc.entity 和 mc.player的区别，player适用与单人，entity适用于多人。 API的设计上似乎有些冗余？还没仔细看这样设计的好处是什么，可以将参数entityId放在最后，默认是0表示当前玩家。

纠正一下之前的理解，entity 指的是生物。

entityIds = mc.getPlayerEntityIds() #get the entity id's of the players connected to the game

1stEntityId = entityIds[0]

2ndEntityId = entityIds[1]

...

.getPos(entityId)

"Gets an entities position in the world as a Vec3 of floats (decimal numbers), if the entity is in the middle of a block x.5 is returned"

entityPos = mc.entity.getPos(entityId) #get first entity position as floats

.setPos(entityId,x,y,z)

"Moves the entity to a position in the world by passing co-ordinates ([x,y,z])"

mc.player.setPos(entityId,0.0,0.0,0.0) #set the players position as floats

.getTilePos(entityId)

"Gets the position of the 'tile' the entity is currently on."

entityTile = mc.entity.getTilePos(entityId) #get the position of the tile the entity is on

.setTilePos(entityId, x,y,z)

"Move the entity to a tile position in the world by passing co-ordinates ([x,y,z])"

mc.player.setTilePos(entityId,0,0,0) #set the position of the tile the entity is on

.getRotation(entityId)

"Get the rotational angle (0 to 360) for an entity => [angle:float]"

angle = mc.entity.getRotation(entityId) #get the rotation of an entity

print angle

.getPitch(entityId)

"Get the pitch angle (-90 to 90) for an entity => [pitch:float]"

pitch = mc.entity.getPitch(entityId) #get the pitch for an entity

print pitch

.getDirection(entityId)

"Get unit vector of x,y,z for an entities direction => [Vec3]"

direction = mc.entity.getDirection(entityId) #get and entities direction

print direction

4. Minecraft.camera

.setNormal(entityId)

"Set camera mode to normal Minecraft view ([entityId])"

Available on Minecraft: Pi Edition

mc.camera.setNormal(entityId) #set camera mode to normal for a specific player

.setFixed()

"Set camera mode to fixed view"

Available on Minecraft: Pi Edition

mc.camera.setFixed() #set camera mode to fixed

.setFollow(entityId)

"Set camera mode to follow an entity ([entityId])"

Available on Minecraft: Pi Edition

mc.camera.setFollow(entityId) #set camera mode to follow for a specific player

.setPos(x,y,z)

"Set camera entity position (x,y,z)"

Available on Minecraft: Pi Edition

mc.camera.setPos(0,0,0) #set camera position to a specific position of x, y, z

5.Minecraft.events

.pollBlockHits()

"Block Hits (Only triggered by sword) => [BlockEvent]"

blockEvents = mc.events.pollBlockHits() #get block event hits that have occured since the last time the function was run

for blockEvent in blockEvents:

print blockEvent

.pollChatPosts()

"Chat posts => [ChatEvent]"

chatEvents = mc.events.pollChatPosts() #get chat post events (messages) since the last time the function was run

for chatEvent in chatEvents:

print chatEvents

.clearAll()

"Clear all old events"

mc.events.clearAll() #clear all events that have happened since the events where last got

6.Block

"The definition of a Block in Minecraft, used to describe a block type and (if applicable) its data; also contains constants for the blocks type id's, e.g. BLOCK.AIR.id"

blockObj = block.Block(id) #create block of a specific type

blockObj = block.Block(id, data) #create a block of a specific type and apply a data value

如何导入包？

import minecraft

import block

.id

"The id (or type) of block"

AIR = Block(0)

STONE = Block(1)

GRASS = Block(2)

DIRT = Block(3)

COBBLESTONE = Block(4)

WOOD_PLANKS = Block(5)

SAPLING = Block(6)

BEDROCK = Block(7)

WATER_FLOWING = Block(8)

WATER = WATER_FLOWING

WATER_STATIONARY = Block(9)

LAVA_FLOWING = Block(10)

LAVA = LAVA_FLOWING

LAVA_STATIONARY = Block(11)

SAND = Block(12)

GRAVEL = Block(13)

GOLD_ORE = Block(14)

IRON_ORE = Block(15)

COAL_ORE = Block(16)

WOOD = Block(17)

LEAVES = Block(18)

GLASS = Block(20)

LAPIS_LAZULI_ORE = Block(21)

LAPIS_LAZULI_BLOCK = Block(22)

SANDSTONE = Block(24)

BED = Block(26)

COBWEB = Block(30)

GRASS_TALL = Block(31)

WOOL = Block(35)

FLOWER_YELLOW = Block(37)

FLOWER_CYAN = Block(38)

MUSHROOM_BROWN = Block(39)

MUSHROOM_RED = Block(40)

GOLD_BLOCK = Block(41)

IRON_BLOCK = Block(42)

STONE_SLAB_DOUBLE = Block(43)

STONE_SLAB = Block(44)

BRICK_BLOCK = Block(45)

TNT = Block(46)

BOOKSHELF = Block(47)

MOSS_STONE = Block(48)

OBSIDIAN = Block(49)

TORCH = Block(50)

FIRE = Block(51)

STAIRS_WOOD = Block(53)

CHEST = Block(54)

DIAMOND_ORE = Block(56)

DIAMOND_BLOCK = Block(57)

CRAFTING_TABLE = Block(58)

FARMLAND = Block(60)

FURNACE_INACTIVE = Block(61)

FURNACE_ACTIVE = Block(62)

DOOR_WOOD = Block(64)

LADDER = Block(65)

STAIRS_COBBLESTONE = Block(67)

DOOR_IRON = Block(71)

REDSTONE_ORE = Block(73)

SNOW = Block(78)

ICE = Block(79)

SNOW_BLOCK = Block(80)

CACTUS = Block(81)

CLAY = Block(82)

SUGAR_CANE = Block(83)

FENCE = Block(85)

GLOWSTONE_BLOCK = Block(89)

BEDROCK_INVISIBLE = Block(95)

STONE_BRICK = Block(98)

GLASS_PANE = Block(102)

MELON = Block(103)

FENCE_GATE = Block(107)

GLOWING_OBSIDIAN = Block(246)

NETHER_REACTOR_CORE = Block(247)

.data

"The data (or sub-type) of a block"

Data Values of blocks:

WOOL:

0: White

1: Orange

2: Magenta

3: Light Blue

4: Yellow

5: Lime

6: Pink

7: Grey

8: Light grey

9: Cyan

10: Purple

11: Blue

12: Brown

13: Green

14: Red

15:Black

WOOD:

0: Oak (up/down)

1: Spruce (up/down)

2: Birch (up/down)

(below not on Pi)

3: Jungle (up/down)

4: Oak (east/west)

5: Spruce (east/west)

6: Birch (east/west)

7: Jungle (east/west)

8: Oak (north/south)

9: Spruce (north/south)

10: Birch (north/south)

11: Jungle (north/south)

12: Oak (only bark)

13: Spruce (only bark)

14: Birch (only bark)

15: Jungle (only bark)

WOOD_PLANKS (Not on Pi):

0: Oak

1: Spruce

2: Birch

3: Jungle

SAPLING:

0: Oak

1: Spruce

2: Birch

3: Jungle (Not on Pi)

GRASS_TALL:

0: Shrub

1: Grass

2: Fern

3: Grass (color affected by biome) (Not on Pi)

TORCH:

1: Pointing east

2: Pointing west

3: Pointing south

4: Pointing north

5: Facing up

STONE_BRICK:

0: Stone brick

1: Mossy stone brick

2: Cracked stone brick

3: Chiseled stone brick

STONE_SLAB / STONE_SLAB_DOUBLE:

0: Stone

1: Sandstone

2: Wooden

3: Cobblestone

4: Brick

5: Stone Brick

Below - not on Pi

6: Nether Brick

7: Quartz

Not on Pi

SNOW_BLOCK:

0-7: Height of snow, 0 being the lowest, 7 being the highest.

TNT:

0: Inactive

1: Ready to explode

LEAVES:

1: Oak leaves

2: Spruce leaves

3: Birch leaves

SANDSTONE:

0: Sandstone

1: Chiseled sandstone

2: Smooth sandstone

STAIRS_[COBBLESTONE, WOOD]:

0: Ascending east

1: Ascending west

2: Ascending south

3: Ascending north

4: Ascending east (upside down)

5: Ascending west (upside down)

6: Ascending south (upside down)

7: Ascending north (upside down)

LADDERS, CHESTS, FURNACES, FENCE_GATE:

2: Facing north

3: Facing south

4: Facing west

5: Facing east

[WATER, LAVA]_STATIONARY:

0-7: Level of the water, 0 being the highest, 7 the lowest

NETHER_REACTOR_CORE:

0: Unused

1: Active

2: Stopped / used up

8. BlockEvent

"The definition of a BlockEvent in Minecraft, used to describe an event in Minecraft affecting blocks; returned by the Minecraft.events.pollBlockHits() method."

.type

"Type of block event; there is only 1 event currently implemented BlockEvent.HIT"

blockEvent = mc.events.pollBlockHits()

blockEventType = blockEvent.type

BlockEvent types:

0: BlockEvent.HIT

.pos

"The position of the block where the event occured, i.e. the block which was hit. .pos returns a Vec3 object of x,y,z co-ordinates"

blockEventPos = BlockEvent.pos

.face

"The face of the block where the event occured"

blockEventFace = BlockEvent.face

.entityId

"entityId of the player who caused the block event, i.e. the player who hit the block"

blockEventPlayer - BlockEvent.entityId

9. ChatEvent

"The definition of a ChatEvent in Minecraft, used to describe an event when a message is posted to the chat bar in Minecraft, returned by Minecraft.events.pollBlockHits() method."

chatEvent = mc.events.pollChatPosts()

.type

"Type of block event; there is only 1 event currently implemented ChatEvent.POST"

chatEventType = chatEvent.type

ChatEvent types:

0: ChatEvent.POST

.message

"The message which was posted to the chat window."

chatEventMessage = ChatEvent.message

.entityId

"entityId of the player who posted the message to the chat."

blockEventPlayer - BlockEvent.entityId

Vec3

"The definition of a 3 part vector in Minecraft, i.e. a set of x, y, z co-ordinates; x and z are the horizontal positions, y the vertical"

position = vec3.Vec(0,0,0)

.x

"x position"

xPos = position.x

.y

"y position"

yPos = position.y

.z

"z position"

zPos = position.z