4. Conversion from mcpi¶
If you have existing scripts that use the reference implementation (minecraft-pi aka mcpi), and you wish to convert them to using the picraft library, this section contains details and examples covering equivalent functionality between the libraries.
4.1. Minecraft.create¶
Equivalent: World
To create a connection using default settings is similar in both libraries:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> from picraft import World
>>> w = World()
Creating a connection with an explicit hostname and port is also similar:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create('localhost', 4711)
>>> from picraft import World
>>> w = World('localhost', 4711)
4.2. Minecraft.getBlock¶
See Minecraft.getBlockWithData below.
4.3. Minecraft.getBlockWithData¶
Equivalent: blocks
Accessing the id of a block is rather different. There is no direct equivalent
to getBlock
, just getBlockWithData
(as there’s no difference in
operational cost so there’s little point in retrieving a block id without the
data). In mcpi this is done by executing a method; in picraft this is done by
querying an attribute with a Vector
:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.getBlock(0, -1, 0)
2
>>> mc.getBlockWithData(0, -1, 0)
Block(2, 0)
>>> from picraft import World, Vector
>>> w = World()
>>> w.blocks[Vector(0, -1, 0)]
<Block "grass" id=2 data=0>
The id and data can be extracted from the Block
tuple
that is returned:
>>> w.blocks[Vector(0, -1, 0)].id
2
>>> w.blocks[Vector(0, -1, 0)].data
0
4.4. Minecraft.setBlock¶
Equivalent: blocks
Setting the id (and optionally data) of a block is also rather different. In
picraft the same attribute is used as for accessing block ids; just assign a
Block
instance to the attribute, instead of querying
it:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.getBlock(0, -1, 0)
2
>>> mc.setBlock(0, -1, 0, 1, 0)
>>> from picraft import World, Vector, Block
>>> w = World()
>>> w.blocks[Vector(0, -1, 0)]
<Block "grass" id=2 data=0>
>>> w.blocks[Vector(0, -1, 0)] = Block(1, 0)
4.5. Minecraft.setBlocks¶
Equivalent: blocks
Again, the same attribute as for setBlock
is used for setBlocks
; just
pass a slice of vectors
instead of a single
vector (the example below shows an easy method of generating such a slice by
adding two vectors together for the upper end of the slice):
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.getBlock(0, -1, 0)
2
>>> mc.setBlocks(0, -1, 0, 0, 5, 0, 1, 0)
>>> from picraft import World, Vector, Block
>>> w = World()
>>> v = Vector(0, -1, 0)
>>> w.blocks[v]
<Block "grass" id=2 data=0>
>>> w.blocks[v:v + Vector(1, 7, 1)] = Block(1, 0)
4.6. Minecraft.getHeight¶
Equivalent: height
Retrieving the height of the world in a specific location is done with an attribute (like retrieving the id and type of blocks). Unlike mcpi, you pass a full vector (of which the Y-coordinate is ignored), and the property returns a full vector with the same X- and Z-coordinates, but the Y-coordinate of the first non-air block from the top of the world:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.getHeight(0, 0)
0
>>> from picraft import World, Vector
>>> w = World()
>>> w.height[Vector(0, -10, 0)]
Vector(x=0, y=0, z=0)
4.7. Minecraft.getPlayerEntityIds¶
Equivalent: players
The connected player’s entity ids can be retrieved by iterating over the
players
attribute which acts as a mapping from
player id to Player
instances:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.getPlayerEntityIds()
[1]
>>> from picraft import World
>>> w = World()
>>> list(w.players)
[1]
4.8. Minecraft.saveCheckpoint¶
Equivalent: save()
Checkpoints can be saved in a couple of ways with picraft. Either you can
explicitly call the save()
method, or you
can use the checkpoint
attribute as a context
manager:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.saveCheckpoint()
>>> from picraft import World
>>> w = World()
>>> w.checkpoint.save()
In the context manager case, the checkpoint will be saved upon entry to the context and will only be restored if an exception occurs within the context:
>>> from picraft import World, Vector, Block
>>> w = World()
>>> with w.checkpoint:
... # Do something with blocks...
... w.blocks[Vector()] = Block.from_name('stone')
4.9. Minecraft.restoreCheckpoint¶
Equivalent: restore()
As with saving a checkpoint, either you can call
restore()
directly:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.saveCheckpoint()
>>> mc.restoreCheckpoint()
>>> from picraft import World
>>> w = World()
>>> w.checkpoint.save()
>>> w.checkpoint.restore()
Or you can use the context manager to restore the checkpoint automatically in the case of an exception:
>>> from picraft import World, Vector, Block
>>> w = World()
>>> with w.checkpoint:
... # Do something with blocks
... w.blocks[Vector()] = Block.from_name('stone')
... # Raising an exception within the block will implicitly
... # cause the checkpoint to restore
... raise Exception('roll back to the checkpoint')
4.10. Minecraft.postToChat¶
Equivalent: say()
The postToChat
method is simply replaced with the
say()
method with the one exception that the latter
correctly recognizes line breaks in the message:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.postToChat('Hello world!')
>>> from picraft import World
>>> w = World()
>>> w.say('Hello world!')
4.11. Minecraft.setting¶
Equivalent: immutable
and nametags_visible
The setting
method is replaced with (write-only) properties with the
equivalent names to the settings that can be used:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.setting('world_immutable', True)
>>> mc.setting('nametags_visible', True)
>>> from picraft import World
>>> w = World()
>>> w.immutable = True
>>> w.nametags_visible = True
4.12. Minecraft.player.getPos¶
Equivalent: pos
The player.getPos
and player.setPos
methods are replaced with the
pos
attribute which returns a
Vector
of floats and accepts the same to move the host
player:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.player.getPos()
Vec3(12.7743,12.0,-8.39158)
>>> mc.player.setPos(12,12,-8)
>>> from picraft import World, Vector
>>> w = World()
>>> w.player.pos
Vector(x=12.7743, y=12.0, z=-8.39158)
>>> w.player.pos = Vector(12, 12, -8)
One advantage of this implementation is that adjusting the player’s position relatively to their current one becomes simple:
>>> w.player.pos += Vector(y=20)
4.13. Minecraft.player.setPos¶
See Minecraft.player.getPos above.
4.14. Minecraft.player.getTilePos¶
Equivalent: tile_pos
The player.getTilePos
and player.setTilePos
methods are replaced with
the tile_pos
attribute which returns a
Vector
of ints, and accepts the same to move the
host player:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.player.getTilePos()
Vec3(12,12,-9)
>>> mc.player.setTilePos(12, 12, -8)
>>> from picraft import World, Vector
>>> w = World()
>>> w.player.tile_pos
Vector(x=12, y=12, z=-9)
>>> w.player.tile_pos += Vector(y=20)
4.15. Minecraft.player.setTilePos¶
See Minecraft.player.getTilePos above.
4.16. Minecraft.player.setting¶
Equivalent: autojump
The player.setting
method is replaced with the write-only
autojump
attribute:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.player.setting('autojump', False)
>>> from picraft import World
>>> w = World()
>>> w.player.autojump = False
4.17. Minecraft.player.getRotation¶
Equivalent: heading
The player.getRotation
method is replaced with the read-only
heading
attribute:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.player.getRotation()
49.048615
>>> from picraft import World
>>> w = World()
>>> w.player.heading
49.048615
4.18. Minecraft.player.getPitch¶
Equivalent: pitch
The player.getPitch
method is replaced with the read-only
pitch
attribute:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.player.getPitch()
4.3500223
>>> from picraft import World
>>> w = World()
>>> w.player.pitch
4.3500223
4.19. Minecraft.player.getDirection¶
Equivalent: direction
The player.getDuration
method is replaced with the read-only
duration
attribute:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.player.getDirection()
Vec3(0.1429840348766887,-0.3263934845430674,0.934356922711132)
>>> from picraft import World
>>> w = World()
>>> w.player.direction
Vector(x=0.1429840348766887, y=-0.3263934845430674, z=0.934356922711132)
4.20. Minecraft.entity.getPos¶
Equivalent: pos
The entity.getPos
and entity.setPos
methods are replaced with the
pos
attribute. Access the relevant
Player
instance by indexing the
players
attribute:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.entity.getPos(1)
Vec3(12.7743,12.0,-8.39158)
>>> mc.entity.setPos(1, 12, 12, -8)
>>> from picraft import World, Vector
>>> w = World()
>>> w.players[1].pos
Vector(x=12.7743, y=12.0, z=-8.39158)
>>> w.players[1].pos = Vector(12, 12, -8)
4.21. Minecraft.entity.setPos¶
See Minecraft.entity.getPos above.
4.22. Minecraft.entity.getTilePos¶
Equivalent: tile_pos
The entity.getTilePos
and entity.setTilePos
methods are replaced with
the tile_pos
attribute. Access the relevant
Player
instance by indexing the
players
attribute:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.entity.getTilePos(1)
Vec3(12,12,-9)
>>> mc.entity.setTilePos(1, 12, 12, -8)
>>> from picraft import World, Vector
>>> w = World()
>>> w.players[1].tile_pos
Vector(x=12, y=12, z=-9)
>>> w.players[1].tile_pos += Vector(y=20)
4.23. Minecraft.entity.setTilePos¶
See Minecraft.entity.getTilePos above.
4.24. Minecraft.entity.getRotation¶
Equivalent: heading
The entity.getRotation
method is replaced with the read-only
heading
attribute:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.entity.getRotation(213)
49.048615
>>> from picraft import World
>>> w = World()
>>> w.players[213].heading
49.048615
4.25. Minecraft.entity.getPitch¶
Equivalent: pitch
The entity.getPitch
method is replaced with the read-only
pitch
attribute:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.entity.getPitch(213)
4.3500223
>>> from picraft import World
>>> w = World()
>>> w.players[213].pitch
4.3500223
4.26. Minecraft.entity.getDirection¶
Equivalent: direction
The entity.getDuration
method is replaced with the read-only
duration
attribute:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.entity.getDirection(213)
Vec3(0.1429840348766887,-0.3263934845430674,0.934356922711132)
>>> from picraft import World
>>> w = World()
>>> w.players[213].direction
Vector(x=0.1429840348766887, y=-0.3263934845430674, z=0.934356922711132)
4.27. Minecraft.camera.setNormal¶
Equivalent: first_person()
The camera
attribute in picraft holds a
Camera
instance which controls the camera in the
Minecraft world. The first_person()
method can be
used to set the camera to view the world through the eyes of the specified
player. The player is specified as the world’s
player
attribute, or as a player retrieved from
the players
attribute:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.camera.setNormal()
>>> mc.camera.setNormal(2)
>>> from picraft import World
>>> w = World()
>>> w.camera.first_person(w.player)
>>> w.camera.first_person(w.players[2])
4.28. Minecraft.camera.setFollow¶
Equivalent: third_person()
The camera
attribute in picraft holds a
Camera
instance which controls the camera in the
Minecraft world. The third_person()
method can be
used to set the camera to view the specified player from above. The player is
specified as the world’s player
attribute, or as a
player retrieved from the players
attribute:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.camera.setFollow()
>>> mc.camera.setNormal(1)
>>> from picraft import World
>>> w = World()
>>> w.camera.third_person(w.player)
>>> w.camera.third_person(w.players[1])
4.29. Minecraft.camera.setFixed¶
Equivalent: pos
The pos
attribute can be passed a
Vector
instance to specify the absolute position of
the camera. The camera will be pointing straight down (y=-1) from the given
position and will not move to follow any entity:
>>> import mcpi.minecraft as minecraft
>>> mc = minecraft.Minecraft.create()
>>> mc.camera.setFixed()
>>> mc.camera.setPos(0,20,0)
>>> from picraft import World, Vector
>>> w = World()
>>> w.camera.pos = Vector(0, 20, 0)
4.30. Minecraft.camera.setPos¶
See Minecraft.camera.setFixed above.
4.31. Minecraft.block.Block¶
Equivalent: Block
The Block
class in picraft is similar to the Block
class in mcpi but with one major difference: in picraft a Block
instance
is a tuple descendent and therefore immutable (you cannot change the id or
data attributes of a Block
instance).
This may seem like an arbitrary barrier, but firstly its quite rare to adjust the the id or data attribute (it’s rather more common to just overwrite a block in the world with an entirely new type), and secondly this change permits blocks to be used as keys in a Python dictionary, or to be stored in a set.
The Block
class also provides several means of
construction, and additional properties:
>>> from picraft import Block
>>> Block(1, 0)
<Block "stone" id=1 data=0>
>>> Block(35, 1)
<Block "wool" id=35 data=1>
>>> Block.from_name('wool', data=1).description
u'Orange Wool'
>>> Block.from_color('#ffffff').description
u'White Wool'