9. API - The World class

The world module defines the World class, which is the usual way of starting a connection to a Minecraft server and which then provides various attributes allowing the user to query and manipulate that world.

Note

All items in this module are available from the picraft namespace without having to import picraft.world directly.

The following items are defined in the module:

9.1. World

class picraft.world.World(host=u'localhost', port=4711, timeout=1.0, ignore_errors=True)[source]

Represents a Minecraft world.

This is the primary class that users interact with. Construct an instance of this class, optionally specifying the host and port of the server (which default to “localhost” and 4711 respectively). Afterward, the instance can be used to query and manipulate the minecraft world of the connected game.

The say() method can be used to send commands to the console, while the player attribute can be used to manipulate or query the status of the player character in the world. The players attribute can be used to manipulate or query other players within the world (this object can be iterated over to discover players):

>>> from picraft import *
>>> world = World()
>>> len(world.players)
1
>>> world.say('Hello, world!')
say(message)[source]

Displays message in the game’s chat console.

The message parameter must be a string (which may contain multiple lines). Each line of the message will be sent to the game’s chat console and displayed immediately. For example:

>>> world.say('Hello, world!')
>>> world.say('The following player IDs exist:\n%s' %
...     '\n'.join(str(p) for p in world.players))
blocks

Represents the state of blocks in the Minecraft world.

This property can be queried to determine the type of a block in the world, or can be set to alter the type of a block. The property can be indexed with a single Vector, in which case the state of a single block is returned (or updated) as a Block object:

>>> world.blocks[g.player.tile_pos]
<Block "grass" id=2 data=0>

Alternatively, a slice of vectors can be used. In this case, when querying the property, a sequence of Block objects is returned, When setting a slice of vectors you can either pass a sequence of Block objects or a single Block object:

>>> world.blocks[Vector(0,0,0):Vector(2,1,1)]
[<Block "grass" id=2 data=0>,<Block "grass" id=2 data=0>]
>>> world.blocks[Vector(0,0,0):Vector(5,1,5)] = Block.from_name('grass')

As with normal Python slices, the interval specified is half-open. That is to say, it is inclusive of the lower vector, exclusive of the upper one. Hence, Vector():Vector(x=5,1,1) represents the coordinates (0,0,0) to (4,0,0). It is usually useful to specify the upper bound as the vector you want and then add one to it:

>>> world.blocks[Vector():Vector(x=1) + 1]
[<Block "grass" id=2 data=0>,<Block "grass" id=2 data=0>]
>>> world.blocks[Vector():Vector(4,0,4) + 1] = Block.from_name('grass')

Finally, you can query an arbitrary collection of vectors. In this case a sequence of blocks will be returned in the same order as the collection of vectors. You can also use this when setting blocks:

>>> d = {
...     Vector(): Block('air'),
...     Vector(x=1): Block('air'),
...     Vector(z=1): Block('stone'),
...     }
>>> l = list(d)
>>> l
[<Vector x=0, y=0, z=0>,<Vector x=1, y=0, z=0>,<Vector x=0, y=0, z=1>]
>>> world.blocks[l]
[<Block "grass" id=2 data=0>,<Block "grass" id=2 data=0>,<Block "grass" id=2 data=0>]
>>> world.blocks[d.keys()] = d.values()

Warning

Querying or setting sequences of blocks can be extremely slow as a network transaction must be executed for each individual block. When setting a slice of blocks, this can be speeded up by specifying a single Block in which case one network transaction will occur to set all blocks in the slice. The Raspberry Juice server also supports querying sequences of blocks with a single command (picraft will automatically use this). Additionally, batch_start() can be used to speed up setting sequences of blocks (though not querying).

camera

Represents the camera of the Minecraft world.

The Camera object contained in this property permits control of the position of the virtual camera in the Minecraft world. For example, to position the camera directly above the host player:

>>> world.camera.third_person(world.player)

Alternatively, to see through the eyes of a specific player:

>>> world.camera.first_person(world.players[2])

Warning

Camera control is only supported on Minecraft Pi edition.

checkpoint

Represents the Minecraft world checkpoint system.

The Checkpoint object contained in this attribute provides the ability to save and restore the state of the world at any time:

>>> world.checkpoint.save()
>>> world.blocks[Vector()] = Block.from_name('stone')
>>> world.checkpoint.restore()
connection

Represents the connection to the Minecraft server.

The Connection object contained in this attribute represents the connection to the Minecraft server and provides various methods for communicating with it. Users will very rarely need to access this attribute, except to use the batch_start() method.

events

Provides an interface to poll events that occur in the Minecraft world.

The Events object contained in this property provides methods for determining what is happening in the Minecraft world:

>>> events = world.events.poll()
>>> len(events)
3
>>> events[0]
<BlockHitEvent pos=1,1,1 face="x+" player=1>
>>> events[0].player.pos
<Vector x=0.5, y=0.0, z=0.5>
height

Represents the height of the Minecraft world.

This property can be queried to determine the height of the world at any location. The property can be indexed with a single Vector, in which case the height will be returned as a vector with the same X and Z coordinates, but a Y coordinate adjusted to the first non-air block from the top of the world:

>>> world.height[Vector(0, -10, 0)]
Vector(x=0, y=0, z=0)

Alternatively, a slice of two vectors can be used. In this case, the property returns a sequence of Vector objects each with their Y coordinates adjusted to the height of the world at the respective X and Z coordinates.

immutable

Write-only property which sets whether the world is changeable.

Warning

World settings are only supported on Minecraft Pi edition.

Note

Unfortunately, the underlying protocol provides no means of reading a world setting, so this property is write-only (attempting to query it will result in an AttributeError being raised).

nametags_visible

Write-only property which sets whether players’ nametags are visible.

Warning

World settings are only supported on Minecraft Pi edition.

Note

Unfortunately, the underlying protocol provides no means of reading a world setting, so this property is write-only (attempting to query it will result in an AttributeError being raised).

player

Represents the host player in the Minecraft world.

The HostPlayer object returned by this attribute provides properties which can be used to query the status of, and manipulate the state of, the host player in the Minecraft world:

>>> world.player.pos
Vector(x=-2.49725, y=18.0, z=-4.21989)
>>> world.player.tile_pos += Vector(y=50)
players

Represents all player entities in the Minecraft world.

This property can be queried to determine which players are currently in the Minecraft world. The property is a mapping of player id (an integer number) to a Player object which permits querying and manipulation of the player. The property supports many of the methods of dicts and can be iterated over like a dict:

>>> len(world.players)
1
>>> list(world.players)
[1]
>>> world.players.keys()
[1]
>>> world.players[1]
<picraft.player.Player at 0x7f2f91f38cd0>
>>> world.players.values()
[<picraft.player.Player at 0x7f2f91f38cd0>]
>>> world.players.items()
[(1, <picraft.player.Player at 0x7f2f91f38cd0>)]
>>> for player in world.players:
...     print(player.tile_pos)
...
-3,18,-5

On the Raspberry Juice platform, you can also use player name to reference players:

>>> world.players['my_player']
<picraft.player.Player at 0x7f2f91f38cd0>

9.2. Checkpoint

class picraft.world.Checkpoint(connection)[source]

Permits restoring the world state from a prior save.

This class provides methods for storing the state of the Minecraft world, and restoring the saved state at a later time. The save() method saves the state of the world, and the restore() method restores the saved state.

This class can be used as a context manager to take a checkpoint, make modifications to the world, and roll them back if an exception occurs. For example, the following code will ultimately do nothing because an exception occurs after the alteration:

>>> from picraft import *
>>> w = World()
>>> with w.checkpoint:
...     w.blocks[w.player.tile_pos - Vector(y=1)] = Block.from_name('stone')
...     raise Exception()

Warning

Checkpoints are only supported on Minecraft Pi edition.

Warning

Minecraft only permits a single checkpoint to be stored at any given time. There is no capability to save multiple checkpoints and no way of checking whether one currently exists. Therefore, storing a checkpoint may overwrite an older checkpoint without warning.

Note

Checkpoints don’t work within batches as the checkpoint save will be batched along with everything else. That said, a checkpoint can be used outside a batch to roll the entire thing back if it fails:

>>> v = w.player.tile_pos - Vector(y=1)
>>> with w.checkpoint:
...     with w.connection.batch_start():
...         w.blocks[v - Vector(2, 0, 2):v + Vector(2, 1, 2)] = [
...             Block.from_name('wool', data=i) for i in range(16)]
restore()[source]

Restore the state of the Minecraft world from a previously saved checkpoint. No facility is provided to determine whether a prior checkpoint is available (the underlying network protocol doesn’t permit this).

save()[source]

Save the state of the Minecraft world, overwriting any prior checkpoint state.

9.3. Camera

class picraft.world.Camera(connection)[source]

This class implements the camera attribute.

first_person(player)[source]

Causes the camera to view the world through the eyes of the specified player. The player can be the player attribute (representing the host player) or an attribute retrieved from the players list. For example:

>>> from picraft import World
>>> w = World()
>>> w.camera.first_person(w.player)
>>> w.camera.first_person(w.players[1])
third_person(player)[source]

Causes the camera to follow the specified player from above. The player can be the player attribute (representing the host player) or an attribute retrieved from the players list. For example:

>>> from picraft import World
>>> w = World()
>>> w.camera.third_person(w.player)
>>> w.camera.third_person(w.players[1])
pos

Write-only property which sets the camera’s absolute position in the world.

Note

Unfortunately, the underlying protocol provides no means of reading this setting, so this property is write-only (attempting to query it will result in an AttributeError being raised).