gdpc.editor¶

Provides the Editor class, which provides high-level functions to interact with the Minecraft world through the GDMC HTTP interface.

class Editor¶

Provides high-level functions to interact with the Minecraft world through the GDMC HTTP interface.

Stores various settings, resources, buffers and caches related to world interaction, and a transform that defines a local coordinate system.

__init__(transformLike: TransformLike | None = None, dimension: str | None = None, buffering: bool = False, bufferLimit: int = 1024, caching: bool = False, cacheLimit: int = 8192, multithreading: bool = False, multithreadingWorkers: int = 1, retries: int = 4, timeout: float | None = None, host: str = 'http://localhost:9000')¶

Constructs an Editor instance with the specified transform and settings.

All settings specified here can be accessed and modified through properties with the same name. For more information on each setting, see the documentation for the corresponding property.

__del__() → None¶

Cleans up this Editor instance.

Flushes the block buffer and waits for any remaining buffer flush futures.

property transform : Transform¶

This editor’s local coordinate transform.

Many of Editor’s methods have a position parameter. In most cases, the passed position vector is interpreted as relative to the coordinate system defined by this property. For example, editor.placeBlock(pos, block) would place block at editor.transform * pos. Changing this property allows you to change the “point of view” of the editor.

For a more comprehensive overview of GDPC’s transformation system, see here.

property dimension : str | None¶

The Minecraft dimension this editor interacts with.

Can be set to any string, though specifying an invalid dimension may cause other Editor methods to raise exceptions. See the documentation of the GDMC HTTP interface mod for the full list of options. The following options are certainly supported:

• "overworld"

• "the_nether"

• "the_end"

• "nether"

• "end"

Changing the dimension will flush the block buffer and invalidate all caches.

Note that transform is NOT reset or modified when the dimension is changed! In particular, the transform’s translation (if any) is NOT adjusted for the nether’s 8x smaller scale.

property buffering : bool¶

Whether block placement buffering is enabled.

When buffering is enabled, blocks passed to placeBlock()/placeBlockGlobal() are not placed immediately, but are instead added to a buffer. When the buffer is full (bufferLimit), all blocks are then placed at once, using a single HTTP request.

The block retrieval functions (such as getBlock()) take the buffer into account: if the buffer contains a block at the specified position, that block is returned. If both buffering and caching (see caching) are enabled, the buffer supersedes the cache for block retrieval.

Note that, if the Minecraft world is changed by something other than the buffering Editor (for example, by a player on the server) after blocks have been buffered but before they have been placed, then the buffered blocks may overwrite those changes.

To manually flush the buffer, call flushBuffer().

property bufferLimit : int¶

Size of the block buffer (see buffering).

property caching : bool¶

Whether caching placed and retrieved blocks is enabled.

When caching is enabled, the last cacheLimit placed and retrieved blocks and their positions are cached in this Editor object. If a block at a cached position is accessed (such as with getBlock()), the block is retrieved from the cache, and no HTTP request is sent.

If both buffering (see buffering) and caching are enabled, the buffer supersedes the cache for block retrieval.

Note that, if the Minecraft world is modified by something other than the caching Editor (for example, by a player on the server), the cache will not reflect those changes, and retrieved blocks may be incorrect.

property cacheLimit : int¶

Size of the block cache (see caching).

property multithreading : bool¶

Whether multithreaded buffer flushing is enabled.

property multithreadingWorkers : int¶

The amount of buffer flush worker threads.

property doBlockUpdates : bool¶

Whether placed blocks receive a block update.

When a player places a block in Minecraft, that block and its surrounding blocks receive a block update.* This triggers effects such as sand blocks falling and fences adjusting their shape.

If this setting is True, blocks placed with placeBlock()/placeBlockGlobal() will be given a block update, just like if they were placed by a player. We recommend leaving this on in most cases.

*: The system is actually a bit more complex than this. See https://minecraft.wiki/w/Block_update for the full details.

property spawnDrops : bool¶

Whether overwritten blocks drop items.

If True, overwritten blocks drop as items (as if they were destroyed with a Silk Touch* tool). Blocks with an inventory (e.g. chests) will drop their inventory as well.

Note that if this is False but :attr:.doBlockUpdates` is True, overwriting a block may still cause a different block to break and drop as an item. For example, if a block with a torch on its side is removed, the torch will drop.

property retries : int¶

The amount of retries for requests to the GDMC HTTP interface.

If a request to the interface fails, it will be retried this many times (1 + this value in total) before an exception is thrown.

property timeout : float | None¶

The timeout for requests to the GDMC HTTP interface

Behaves as described by the requests package).

property host : str¶

The address (hostname+port) of the GDMC HTTP interface to use.

Changing the host will flush the buffer and invalidate all caches.

Note that the transform is NOT reset or modified when the host is changed!

property worldSlice : WorldSlice | None¶

The cached WorldSlice (see loadWorldSlice()).

property worldSliceDecay : ndarray[tuple[int, ...], dtype[bool]] | None¶

3D boolean array indicating whether the block at the specified position in the cached worldSlice is still valid.

Note that the lowest Y-layer is at [:,0,:], despite Minecraft’s negative Y coordinates. If worldSlice is None, this property will also be None.

runCommand(command: str, position: Vec3iLike | None = None, syncWithBuffer: bool = False) → None¶

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

The leading “/” must be omitted.

If buffering is enabled and syncWithBuffer is True, the command is deferred until after the next buffer flush. This can be useful if the command depends on possibly buffered block changes.

If position is provided, the command’s execution position is set to position, where position is interpreted as local to transform. This means that, for example, the position “~ ~ ~” in the command will correspond to position. Note however that any rotation or flip performed by transform is NOT reflected in the command’s execution context! This means that the use of local coordinate offsets (e.g. “^1 ^2 ^3”) is in general not safe. For more details about relative and local command coordinates, see https://minecraft.wiki/Coordinates#Commands

runCommandGlobal(command: str, position: Vec3iLike | None = None, syncWithBuffer: bool = False) → None¶

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

The leading “/” must be omitted.

If buffering is enabled and syncWithBuffer is True, the command is deferred until after the next buffer flush. This can be useful if the command depends on possibly buffered block changes.

If position is provided, the command’s execution position is set to position, ignoring transform. This means that, for example, the position “~ ~ ~” in the command will correspond to position. For more details about relative and local command coordinates, see https://minecraft.wiki/Coordinates#Commands

getBuildArea() → Box¶

Returns the build area that was specified by /setbuildarea in-game.

The build area is always in global coordinates; transform is ignored.

setBuildArea(buildArea: Box) → Box¶

Sets the build area to buildArea, and returns it.

The build area must be given in global coordinates; transform is ignored.

getBlock(position: Vec3iLike) → Block¶

Returns the block at position.

position is interpreted as local to the coordinate system defined by transform. The returned block’s orientation is also from the perspective of transform.

If the given coordinates are invalid, returns Block("minecraft:void_air").

getBlockGlobal(position: Vec3iLike) → Block¶

Returns the block at position, ignoring transform.

If the given coordinates are invalid, returns Block("minecraft:void_air").

getBiome(position: Vec3iLike) → str¶

Returns the biome at position.

position is interpreted as local to the coordinate system defined by transform.

If the given coordinates are invalid, returns an empty string.

getBiomeGlobal(position: Vec3iLike) → str¶

Returns the biome at position, ignoring transform.

If the given coordinates are invalid, returns an empty string.

placeBlock(position: Vec3iLike | Iterable[Vec3iLike], block: Block | Sequence[Block], replace: str | list[str] | None = None) → bool¶

Places block at position.

position is interpreted as local to the coordinate system defined by transform.

If position is iterable (e.g. a list), block is placed at all positions. This is more efficient than calling this method in a loop.

If block is a sequence (e.g. a list), blocks are sampled randomly.

Returns whether the placement succeeded fully.

placeBlockGlobal(position: Vec3iLike | Iterable[Vec3iLike], block: Block | Sequence[Block], replace: str | Iterable[str] | None = None) → bool¶

Places block at position, ignoring transform.

If position is iterable (e.g. a list), block is placed at all positions. In this case, buffering is temporarily enabled for better performance.

If block is a sequence (e.g. a list), blocks are sampled randomly.

Returns whether the placement succeeded fully.

flushBuffer() → None¶

Flushes the block placement buffer.

If multithreaded buffer flushing is enabled, the worker threads can be awaited with awaitBufferFlushes().

awaitBufferFlushes(timeout: float | None = None) → None¶

Awaits all pending buffer flushes.

If timeout is not None, waits for at most timeout seconds.

Does nothing if no buffer flushes have occured while multithreaded buffer flushing was enabled.

loadWorldSlice(rect: Rect | None = None, heightmapTypes: Iterable[str] | None = None, cache: bool = False) → WorldSlice¶

Loads the world slice for the given XZ-rectangle.

The rectangle must be given in global coordinates; transform is ignored.

If rect is None, the world slice of the current build area is loaded.

If heightmapTypes is None, all heightmaps are loaded.

If cache is True, the loaded worldSlice is cached in this editor. It can then be accessed through worldSlice. If a world slice was already cached, it is replaced. The cached world slice is used for faster block and biome retrieval. Note that the editor assumes that nothing besides itself changes the given area of the world. If the given world area is changed other than through this editor, call updateWorldSlice() to update the cached world slice.

updateWorldSlice() → WorldSlice¶

Updates the cached world slice.

Loads and caches new world slice for the same area and with the same heightmaps as the currently cached one. Raises a RuntimeError if no world slice is cached.

getMinecraftVersion() → str¶

Returns the Minecraft version as a string.

checkConnection() → None¶

Raises an InterfaceConnectionError if the GDMC HTTP interface cannot be reached.

Does not perform any retries.

pushTransform(transformLike: TransformLike | None = None) → Generator[None, None, None]¶

Creates a context that reverts all changes to transform on exit. If transformLike is not None, it is pushed to transform on enter.

Can be used to create a local coordinate system on top of the current local coordinate system.

Not to be confused with Transform.push()!