class World

Manipulating the world is the heart piece of the entire library. With this you can query blocks and world features and set them in turn, as well as finding and spawning entities in the world. This allows building on the server quickly and precisely with only a few commands. Note that all commands of World will only manipulate that world, for example, getEntities() will only return entities in this world.

Do not instantiate the World class directly but use one of the following methods instead:

worlds = mc.worlds
world = mc.overworld
world = mc.nether
world = mc.end
someotherworld = mc.getWorldByKey("mod_namespace:world_key")

Once you have your world you can use it in a multitude of ways:

world.pvp = False  # disable pvp only in this world
ground_pos = world.getHeighestPos(0, 0)  # get position of heighest ground at origin
block = world.getBlock(ground_pos)  # get the block type there
world.setBlock("diamond_block", ground_pos)  # replace that block at location with diamond
# set every second block in a line along the x axis to emerald
world.setBlockList("emerald_block", [ground_pos.up(2).east(i) for i in range(0,20,2)])
# set a 10 x 10 x 10 oak plank block 50 blocks above ground
world.setBlockCube("oak_planks", ground_pos.up(50), ground_pos.up(50) + 9)
sheep = world.spawnEntity("sheep", ground_pos.up(1))  # spawn a sheep on that block
entities = world.getEntities()  # get all (loaded) entities
# get all  (loaded) entities around origin highest block in 20 block radius
entities = world.getEntitiesAround(ground_pos, 20)
world.removeEntities("sheep")  # remove all (loaded) sheep
# copy all blocks between those two points (inclusive)
blocks = world.copyBlockCube(Vec3(0,0,0), Vec3(5,5,5))
# paste back the copied blocks 20 blocks above origin ground
world.pasteBlockCube(blocks, ground_pos.up(20))
world.setBed(ground_pos.up(1))  # place a bed on top of diamond block

Note

When using the world functions on Minecraft (mc) directly the ‘default’ world is used. The default world is defined by the server as the first world loaded by the server, which is usually the overworld. If you want to affect a specific world, use World classes instead, such as mc.overworld, mc.nether or mc.end.

property key: str

The key/id of this world, e.g., "minecraft:overworld" or "minecraft:the_nether"

property name: str

The name of the folder/namespace the world resides in, e.g., "world" or "world_the_end"

property pvp: bool

True if pvp is enabled in this world. Can be set to enable or disable pvp in only this world.

runCommand(command: str) → None

Run the command as if it was typed in chat as /-command and executed in this specific world/dimension..

world.runCommand("kill @e")  # kill all loaded entities in this world
Parameters:

command (str) – the command without the slash /

getHighestPos(x: int, z: int) → Vec3

The position of the highest non-air block with given x and z in the world.

Returns:

The position of the highest non-air block with given x and z

Return type:

Vec3

getHeight(x: int, z: int) → int

Equivalent to the y value of getHighestPos() with x and z.

getBlock(pos: Vec3) → str

The block type/id at position pos in world.

Note

The function does only query the block type/id, no additional block data is included.

Parameters:

pos (Vec3) – position to query block from

Returns:

block type/id at queried position

Return type:

str

getBlockList(positions: list[Vec3]) → list[str]

The list of all block types/ids at given positions in world in the same order.

Note

The function does only query the block types/ids, no additional block data is included.

Parameters:

positions (list[Vec3]) – list of positions to query

Returns:

list of block types/ids at given positions (same order)

Return type:

list[str]

setBlock(blocktype: str, pos: Vec3) → None

Change the block at position pos to blocktype in world. This will overwrite any block at that position.

Parameters:

  • blocktype (str) – the valid block type/id to set the block to

  • pos (Vec3) – the position where the block should be set

setBed(pos: Vec3, direction: Literal['east', 'south', 'west', 'north'] = 'east', color: Literal['white', 'orange', 'magenta', 'light_blue', 'yellow', 'lime', 'pink', 'gray', 'light_gray', 'cyan', 'purple', 'blue', 'brown', 'green', 'red', 'black'] = 'red') → None

Place a bed at pos in direction with color, which is composed of two placed blocks with specific block data.

Parameters:

  • pos (Vec3) – the position of foot part of bed

  • direction (CARDINAL, optional) – direction in which to place head part of bed, defaults to “east”

  • color (COLOR, optional) – color of bed, defaults to “red”

setBlockList(blocktype: str, positions: list[Vec3]) → None

Change all blocks at positions to blocktype in world. This will overwrite all blocks at the given positions. This is more efficient that using setBlock() mutliple times with the same blocktype.

Parameters:

  • blocktype (str) – the valid block type/id to set the blocks to

  • positions (list[Vec3]) – the positions where the blocks should be set

setBlockCube(blocktype: str, pos1: Vec3, pos2: Vec3) → None

Change all blocks in a cube between the corners pos1 and pos2 in world to blocktype, where both positions are inclusive. meaning that both given positions/corners will be part of the cube. This will overwrite all blocks between the given positions. The positions span a cube if all their coordinates are different, a plane if one of their coordinates is the same or a line if two of their three coordinates are the same.

# xlen, ylen, zlen are the length of the cube in the specified axis
start = Vec3()  # this would be the lowest (most negative coordinates) corner of the cube we want to draw, here origin
world.setBlockCube("diamond_block", start, start.addX(xlen).addY(ylen).addZ(zlen))

# this is equivalent to (but more efficent and faster than)

for x in range(xlen + 1):
    for y in range(ylen + 1):
        for z in range(zlen + 1):
            world.setBlock("diamond_block", start.addX(x).addY(y).addZ(z))
Parameters:

  • blocktype (str) – the valid block type/id to set the blocks to

  • pos1 (Vec3) – the position of one corner of the cube

  • pos2 (Vec3) – the position of the opposite corner of the cube

copyBlockCube(pos1: Vec3, pos2: Vec3) → list[list[list[str]]]

Get all block types in a cube between pos1 and pos2 inclusive. Should be used in conjunction with pasteBlockCube().

Note

The function does only copy the block types/ids, no additional block data is included.

Parameters:

  • pos1 (Vec3) – the position of one corner of the cube

  • pos2 (Vec3) – the position of the opposite corner of the cube

Returns:

the block types in the cube given as rows of x with columns of y with slices of depth z respectively

Return type:

list[list[list[str]]]

pasteBlockCube(blocktypes: list[list[list[str]]], pos: Vec3, rotation: Literal['east', 'south', 'west', 'north', 'up', 'down'] = 'east', flip_x: bool = False, flip_y: bool = False, flip_z: bool = False) → None

Paste the block types in the cube blocktypes into the world at position pos where pos is the negative most corner of the cube along all three axes. Additional options can be used to change the rotation of blocks in the copied cube, however, no matter in which way the cube is rotated and/or flipped, pos will also be the most negative corner. Should be used in conjunction with copyBlockCube().

Note

The copyBlockCube() function does only copy the block types/ids, no additional block data is included.

start = Vec3(0, 0, 0)
end = start.addX(5).addY(5).addZ(5)
# copy a 6x6x6 block cube from origin in world
blocks = world.copyBlockCube(start, end)
# replace that space with the same blocks but rotated by 90 degrees
world.pasteBlockCube(blocks, start, "south")
# copy same original block at different point above origin
world.pasteBlockCube(blocks, start.up(200))
Parameters:

  • blocktypes (list[list[list[str]]]) – the cube of block types/ids that should be pasted, given as rows of x with columns of y with slices of depth z respectively

  • pos (Vec3) – the most negative corner along all three axes of the cube where the cube should be pasted

  • rotation (DIRECTION, optional) – the direction of the x axis of the cube to be pasted (“east” means copied x axis aligns with real x axis, i.e., the original orientation), defaults to “east”

  • flip_x (bool, optional) – flip pasted blocks along x axis, defaults to False

  • flip_y (bool, optional) – flip pasted blocks along y axis, defaults to False

  • flip_z (bool, optional) – flip pasted blocks along z axis, defaults to False

spawnEntity(type: str, pos: Vec3) → Entity

Spawn and return a new entitiy of given type at position pos in world. The entity has default settings and behavior.

Parameters:

  • type (str) – the valid entity type that should be spawned (must be spawnable without additional parameters)

  • pos (Vec3) – the position where to spawn the entitiy in the world

Returns:

the Entity entity spawned

Return type:

entity.Entity

spawnItems(pos: Vec3, type: str, amount: int = 1) → None

Spawn amount many collectable items of type at pos.

Parameters:

  • pos (Vec3) – position where to spawn the items

  • type (str) – the item type, e.g., "minecraft:arrow"

  • amount (int, optional) – number of items to spawn, defaults to 1

getEntities(type: str | None = None, only_spawnable: bool = True) → list[Entity]

Get all (loaded) entities in the world. If a type is provided, only entities of that type are returned. By default only entities of types that could be spawned using spawnEntity() are returned. To get all entities (except players) set only_spawnable=False, which will also return non-spawnable entities such as e.g. "falling_block" or "dropped_item".

Parameters:

  • type (str | None, optional) – if provided returns only entities of that type, returns all types if None, defaults to None

  • only_spawnable (bool, optional) – if False, will also return non-spawnable entities, defaults to True

Returns:

list of (loaded and filtered) entities in the world

Return type:

list[entity.Entity]

getEntitiesAround(pos: Vec3, distance: float, type: str | None = None, only_spawnable: bool = True) → list[Entity]

Equivalent to getEntities(), however, is filtered to only return entities within distance around pos. Is more efficient that filtering the list manually.

Parameters:

  • pos (Vec3) – position around which the entities are returned

  • distance (float) – the maximum distance entities returned have around pos

  • type (str | None, optional) – if provided returns only entities of that type, returns all types if None, defaults to None

  • only_spawnable (bool, optional) – if False, will also return non-spawnable entities, defaults to True

Returns:

list of (loaded and filtered) entities in the world closer than distance to pos

Return type:

list[entity.Entity]

removeEntities(type: str | None = None) → None

Remove all entities (except players) from the world, they do not drop anything. If type is provided remove only entities of that type.

Parameters:

type (str | None, optional) – if provided removes only entities of that type, otherwise remove all entities, defaults to None