gdpc.interface

Provides direct wrappers for the endpoints of the GDMC HTTP interface.

These functions are quite low-level. If possible, it is recommended to use the higher-level Editor class instead. However, some GDMC HTTP interface features that this module wraps may not be supported by Editor yet. You may find this module useful for those.


DEFAULT_HOST = 'http://localhost:9000'

Default host

getBlocks(position: Vec3iLike, size: Vec3iLike | None = None, dimension: str | None = None, includeState: bool = True, includeData: bool = True, retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → list[tuple[ivec3, Block]]

Returns the blocks in the specified region.

dimension can be one of {“overworld”, “the_nether”, “the_end”} (default “overworld”).

Returns a list of (position, block)-tuples.

For positions outside the vertical world limit, the returned block ID will be “minecraft:void_air”.

getBiomes(position: Vec3iLike, size: Vec3iLike | None = None, dimension: str | None = None, retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → list[tuple[ivec3, str]]

Returns the biomes in the specified region.

dimension can be one of {“overworld”, “the_nether”, “the_end”} (default “overworld”).

Returns a list of (position, biome id)-tuples.

For positions outside the vertical world limit, an empty string is returned instead of a biome ID.

placeBlocks(blocks: Iterable[tuple[Vec3iLike, Block]], dimension: str | None = None, doBlockUpdates: bool = True, spawnDrops: bool = False, customFlags: str = '', retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → list[tuple[bool, int | str]]

Places blocks in the world.

Each element of blocks should be a tuple (position, block). Empty blocks (blocks without an id) are not allowed.

dimension can be one of {“overworld”, “the_nether”, “the_end”} (default “overworld”).

The doBlockUpdates, spawnDrops and customFlags parameters control block update behavior. See the GDMC HTTP API documentation for more info.

Returns a list of (success, result)-tuples, one for each block. Each tuple is set according to one of three scenarios:

  1. Block placement succeeded, and the block at the target position was changed. In this case, success is True and result is 1.

  2. Block placement succeeded, but the block at the target position was not changed (the block already was what you tried to set it to). In this case, success is True and result is 0.

  3. Block placement failed. In this case, success is False and result is an error message.

runCommand(command: str, dimension: str | None = None, retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → list[tuple[bool, str | None]]

Executes one or multiple Minecraft commands (separated by newlines).

The leading “/” must be omitted.

dimension can be one of {“overworld”, “the_nether”, “the_end”} (default “overworld”).

Returns a list of (success, result)-tuples, one for each command. If a command was succesful, result is its return value (if any). Otherwise, it is the error message.

getBuildArea(retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → Box

Retrieves the build area that was specified with /setbuildarea in-game.

Raises a BuildAreaNotSetError if the build area was not specified yet.

If a build area was specified, result is the box describing the build area.

getChunks(position: Vec2iLike, size: Vec2iLike | None = None, dimension: str | None = None, asBytes: bool = False, retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → str | bytes

Returns raw chunk data.

position specifies the position in chunk coordinates, and size specifies how many chunks to get in each axis (default 1). dimension can be one of {“overworld”, “the_nether”, “the_end”} (default “overworld”).

If asBytes is True, returns raw binary data. Otherwise, returns a human-readable representation.

On error, returns the error message instead.

placeStructure(structureData: bytes | NBTFile, position: Vec3iLike, mirror: Vec2iLike | None = None, rotate: int | None = None, pivot: Vec3iLike | None = None, includeEntities: bool | None = None, dimension: str | None = None, doBlockUpdates: bool = True, spawnDrops: bool = False, customFlags: str = '', retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → None

Places a structure defined using the Minecraft structure format in the world.

structureData should be a string of bytes in the Minecraft structure file format, the format used by the in-game structure blocks. You can extract structures in this format in various ways, such as using the GET /structure endpoint of GDMC-HTTP or the aformentioned in-game structure blocks. structureData can also be an instance of nbt.NBTFile. Using this library has the benefit of providing ways for modifying data before placing it in Minecraft.

See the GDMC HTTP API documentation for more information about these parameters.

getStructure(position: Vec3iLike, size: Vec3iLike, dimension: str | None = None, includeEntities: bool | None = None, returnCompressed: bool | None = True, retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → bytes

Returns the specified area in the Minecraft structure file format (an NBT byte string).

The Minecraft structure file format is the format used by the in-game structure blocks. Structures in this format are commonly saved in .nbt files, and can be placed using tools such as the POST /structure endpoint of GDMC-HTTP or the aforementioned in-game structure blocks.

Setting the includeEntities to True will attach all entities present in the given area at the moment of calling getStructure to the resulting data. Meaning that saving a house in a Minecraft village will include the NPC living inside it. Note that when placing this structure using GDMC-HTTP, the includeEntities parameter needs to be set to True for these entities to be placed into the world together with the blocks making up the structure.

getHeightmap(position: Vec3iLike | None = None, size: Vec3iLike | None = None, heightmapType: str | None = None, blocks: Iterable[str] | None = None, yMin: int | None = None, yMax: int | None = None, dimension: str | None = None, retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → ndarray[tuple[int, ...], dtype[int64]]

Returns heightmap of the given type within the current build area.

This endpoint supports four of Minecraft’s built-in heightmap types:

  • 'WORLD_SURFACE': Height of the surface ignoring air blocks.

  • 'OCEAN_FLOOR': Height of the surface ignoring air, water, and lava.

  • 'MOTION_BLOCKING': Height of the surface ignoring blocks that don’t have movement collision (air, flowers, ferns, etc.), except for water and lava.

  • 'MOTION_BLOCKING_NO_LEAVES': Same as 'MOTION_BLOCKING', but also ignores leaves.

Additionally, the GDMC-HTTP mod provides two extra heightmap types, which can only be retrieved using this endpoint:

  • 'MOTION_BLOCKING_NO_PLANTS': Same as 'MOTION_BLOCKING_NO_LEAVES', but also excludes various biological block types. For a full list, refer to the GDMC-HTTP documentation.

  • 'OCEAN_FLOOR_NO_PLANTS': Same as 'OCEAN_FLOOR', except it also excludes everything that is part of 'MOTION_BLOCKING_NO_PLANTS'.

Instead of a heightmap type, you can also submit a list of block IDs using the blocks parameter. These are the blocks that should be considered “transparent” when the heightmap is calculated. Note: Air blocks ('minecraft:air', 'minecraft:cave_air') aren’t included by default.

Using the yMin and yMax parameters, the lower and/or upper limit of the heightmap calculation can be constrained. This can be useful for creating heightmaps of overworld caves or the Nether dimension. Only works if used in conjunction with the blocks parameter.

placeEntities(entities: Iterable[dict[str, str | int]], position: Vec3iLike, dimension: str | None = None, retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → Any

Place entities (animals, paintings, item frames, etc.).

Requires list of dicts, each containing the id string of the entity (for instance, 'minecraft:cat'), the spawn x, y and z position (can be relative to the position argument). Optionally, providing the data attribute with a SNBT-formatted string sets non-default properties to the entity.

updateEntities(entities: Iterable[dict[str, str]], dimension: str | None = None, retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → Any

Update specific entities (animals, paintings, item frames, etc.) already present in the world.

Requires list of dicts, each containing the uuid string of the entity in the world and data SNBT-formatted string of entity properties that need to be patched.

removeEntities(entities: Iterable[str], dimension: str | None = None, retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → Any

Remove specific entities (animals, paintings, item frames, etc.) already present in the world.

Requires list of UUID strings of the entities that need to be removed.

getEntities(selector: str | None = None, includeData: bool = True, dimension: str | None = None, retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → Any

Retrieve data on entities in the world matching the given target selector query.

getPlayers(selector: str | None = None, includeData: bool = True, dimension: str | None = None, retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → Any

Retrieve data on player entities in the world matching the given target selector query.

getVersion(retries: int = 0, timeout: Any = None, host: str = 'http://localhost:9000') → str

Returns the Minecraft version as a string.