Minecraft API

原链接：https://www.stuffaboutcode.com/p/minecraft-api-reference.html
源代码：https://github.com/martinohanlon/mcpi
https://github.com/zhuowei/RaspberryJuice

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