MCIWB API

This is the public API reference for MCIWB

MCIWB is built upon further libraries. The dependencies look like this:

Libraries

Library	URL	Function
RCON	conqp/rcon	Provides the raw RCON interface to Minecraft
MCIPC	conqp/mcipc	Adds useful types to RCON creating a neat Python API for Minecraft
MCWB	mcipc-tools/mcwb	Adds a world builder API to MCIPC that creates complex objects in the world
MCIWB	gilesknap/mciwb	Adds interactive features to MCWB

mciwb

mciwb.__version__: str

Version number as calculated by pypa/setuptools_scm

mciwb.iwb

class mciwb.iwb.Iwb(server: str, port: int, passwd: str)

Interactive World Builder class. Provides a very simple interface for interactive functions for use in an IPython shell.

Variables:

• player – The default Player object.

• copier – CopyPaste object for the above player.

• signs – The Signs object for the above player.

Initialise the world object.

Parameters:

• server – the server address

• port – the server port

• passwd – the server password

Raises:

SessionTimeout – if the connection to the server fails

debug(enable: bool = True)

Enable/disable debug log. Enabling this will also enable full Traceback log.

Parameters:

enable – True to enable debug log, False to disable

backup(name=None) → None

Backup the Minecraft world to a file. If no name is given then the backup will be named using the current date and time.

Parameters:

name – the name of the backup file

connect() → Client

Makes a connection to the Minecraft Server. Can be called again if the connection is lost e.g. due to server reboot.

get_player(name: str) → Player

Get the player object for the given player name.

Parameters:

name – the name of the player

property players: List[str]

Get a list of the names of players being monitored.

add_player(name: str, me=True)

Add a player to the world object. This provides monitoring of the player’s position and handles the player’s placing of action signs.

If me is True then the player will be set as the current default player. The default player is available using:

Iwb.the_world.player

All players are available using:

Iwb.the_world._players

Parameters:

• name – the name of the player

• me – if True, set this player as the default player

set_block(pos: Vec3, block: Item, facing: Vec3 | None = None, nbt: List[str] | None = None)

Places a block in the world

Parameters:

• pos – the position to place the block

• block – the type of block

• facing – the direction the block should face (if applicable)

• nbt – a list of NBT tags to apply to the block

nbt examples:

Placing a top half of a door, open, with hinge on the left:

nbt=[“half=upper”, “hinge=left”, “open=true”]

TODO at present the nbt are free form strings. In the spirit of mcwb we should provide a set of types that represent the NBT tags and provide a way to convert them to strings (but that is a large task)

get_block(pos: Vec3) → Item

Gets a block in the world

Parameters:

pos – the position to get the block from

save(filename: str, vol: Volume | None = None)

Save a Volume of blocks to a file. The volume can be specified in the vol parameter or alternatively defaults to the current copy buffer.

The file is saved in the mcwb format which is a JSON file containing a 3d array of Item objects.

The file can be loaded into a world using the load method.

Parameters:

• filename – the name of the file to save to

• vol – the volume to save

load(filename: str, position: Vec3 | None = None, anchor: Anchor3 = Anchor3.BOTTOM_SW)

Load a saved set of blocks into a location. The location can be specified in argument position or alternatively defaults to the copy buffer start position.

The blocks are loaded from a file in the mcwb format which is a JSON file containing a 3d array of Item objects.

The blocks are loaded into the world using the Blocks class.

Parameters:

• filename – the name of the file to load from

• position – the position to load the blocks to

• anchor – the anchor point for the blocks

cmd(cmd: str) → str

Run any arbitrary Minecraft console command on the server.

Parameters:

cmd – the command to run

mciwb.player

Represent a player in the world and provide functions for monitoring their state

class mciwb.player.Player(name: str)

Represent a player in the world and provide functions for monitoring their position and direction they are facing.

property inventory: List[str]

Get the player’s inventory

property pos_f: Vec3

Return the player’s precise position

property pos: Vec3

Return the player’s block position

property facing: Vec3

Return the player’s facing direction

Returns:

a Vec3 representing the direction the player is facing NORTH = Vec3(0, 0, -1) SOUTH = Vec3(0, 0, 1) EAST = Vec3(1, 0, 0) WEST = Vec3(-1, 0, 0)

property rotation: Tuple[float, float]

Get the player’s rotation in degrees

player_in(volume: Volume) → bool

Check if the player is inside the Volume

Parameters:

volume – the volume of blocks to check

classmethod players_in(volume: Volume) → List[Player]

return a list of player names whose position is inside the Volume

mciwb.server

Functions for launching and controlling a Minecraft server in a Docker container.

class mciwb.server.MinecraftServer(name: str, rcon: int, password: str, server_folder: Path, world_type: str, backup_folder: Path = None, keep: bool = True, test=False)

Create an monitor Minecraft servers on the local machine using Docker

Parameters:

• name – the name of the server

• rcon – the rcon port for the server

• password – the rcon password for the server

• server_folder – the folder to store the server files in

• world_type – the type of world to create

• keep – keep the server running after tests

• test – run the server in test mode

Create a MinecraftServer object only. Use create to spin up the container.

wait_server()

Wait until the server is ready to accept rcon connections

stop()

Stop the minecraft server

start()

Start the minecraft server

remove(force=False)

Remove a minecraft server container

Parameters:

force – force the removal of the container

create(world_zip=None, force=False) → None

Spin up a minecraft server in a container

Parameters:

• world_zip – the zip file to use as the world data. If None is provided, a new world will be created.

• force – force the server to be removed if it already exists

classmethod stop_named(name: str)

Stop a minecraft server by name

Parameters:

name – the name of the server to stop

mciwb.monitor

Thread functions for running any background tasks. Primarily used for monitoring the state of objects in Minecraft.

class mciwb.monitor.Monitor(func: None | Callable = None, params: Tuple[Any, ...] = (), once=False, name=None, poll_rate=0.2, start=True)

” A class to provide threads for monitoring. Each thread maintains a list of functions to call repeatedly.

Each thread has its own Client object for parallel execution of Minecraft server functions.

Parameters:

• name – name of the thread

• func – a function to call in the Monitor thread

• params – parameters to pass to the above function. Note that func and params can be None, () in which case you must use add_poller_func to add functions to be called.

• poll_rate – rate at which to poll the functions

• once – if True, stop polling after first poll - use for a single background operation

• start – if True, start the thread immediately

start_poller()

Begin polling the functions in the pollers list

add_poller_func(func: Callable, params: Tuple[Any, ...] = ())

Add a function to the pollers list

Parameters:

• func – function to add

• params – parameters to pass to the function

remove_poller_func(func: Callable)

Remove a function from the pollers list

Parameters:

func – function to remove

classmethod stop_all()

Stop all instances of Monitor and tidy up. Call this before exiting the program otherwise Python will wait on the background threads indefinitely.

stop()

Stop this instance of Monitor

classmethod stop_named(name: str)

Stop a named instance of Monitor

mciwb.backup

mciwb.signs

Add an interactive capability through the placing of command signs in the world

class mciwb.signs.Signs(player: Player)

Monitor the world for signs placed by a player. Perform an action based on the text of the sign.

Each sign object can be used to monitor the placing of signs by a single player. The object can be hooked to functions that are to be called when a sign is placed by the player.

By default each Sign object is initialized with select/copy/paste functions. Additional signs with callback functions can be added.

For best results, use the bound methods of an object for the callback functions. That way the user code can manage state within the object providing those functions.

do_action(command: str, target: Vec3, block_pos: Vec3)

Perform an action based on the text of the sign. The action is to call the callback function that is configured for this sign text.

Parameters:

• command – the text of the sign

• target – the target block that the sign indicates

• block_pos – the position of the block that the sign is on - this is cleared if the sign is used

add_sign(name: str, function: Callable[[Vec3], None])

Add a new sign type with its action callback function

Parameters:

• name – the text of the sign

• function – the callback function to be called when the sign is placed

remove_sign(name: str)

Stop monitoring for a sign with the given name

Parameters:

name – the text of the sign

give_signs()

Give player one of each command sign in our commands list

Check first if the player has the sign already

mciwb.copier

Provide copy and paste actions on Volumes of blocks

class mciwb.copier.CopyPaste

Provides an interactive way to use copy and paste commands within a Minecraft world.

to_volume() → Volume

Converts the copy buffer location and dimensions to a Volume

apply_volume(vol: Volume)

Use a Volume to set the copy buffer location and dimensions

get_commands()

return a list of command names and the callback functions they represent. For use in setting up a Signs object that can be used to interactively call the copy paste functions.

select(pos: Vec3)

Select a new copy buffer start point in the world. The previous start point becomes the stop point (i.e. opposite corner of the paste buffer)

paste(pos: Vec3, force=True)

Copy the contents of past buffer to pos

paste_safe(pos: Vec3)

Paste the contents of the paste buffer to pos, but only if the paste buffer does not overlap with the target area

fill(pos: Vec3 = (0, 0, 0), item: Item = Item.AIR)

fill the paste buffer offset by pos with Air or a specified block

Parameters:

• pos – offset from the paste buffer start point

• item – block to fill with

clear(_: Vec3 = (0, 0, 0))

Clear the blocks in the current paste buffer

expand_to(pos: Vec3)

expand one or more of the dimensions of the copy buffer by moving the faces outwards to the specified point

expand(x=0, y=0, z=0)

expand one or more of the dimensions of the copy buffer by relative amounts

mciwb.switch

mciwb.switch.item_types = {'BUTTON': '[face=floor, facing=north]', 'LEVER': '[face=floor, facing=north]', 'PRESSURE_PLATE': '[]', 'TRIPWIRE_HOOK': '[]'}

supported switch types and the properties to set on them

class mciwb.switch.Switch(position: Vec3, item: Item, callback: Callable[[Switch], None], name: str = '')

Defines a class for representing a lever, button or any other activator in the world. Implements monitoring of the switch’s state with callbacks.

Parameters:

• position – the position of the switch in the world

• item – the item type of the switch (must be one of item_types)

• callback – the callback to call when the switch’s state changes

• name – the name of the switch (defaults to “switch” + id)

Variables:

• id – the id of the switch

• name – the name of the switch

• pos – the position of the switch in the world

• powered – the current state of the switch (True if powered)

• callback – the callback to call when the switch’s state changes

• monitor – the Monitor object for the switch

• switches – the list of all switches in the world

• next_id – the next id to assign to a switch

• on – the state to check for a powered switch

• off – the state to check for an un-powered switch

• monitor – the Monitor object for the switch

classmethod remove_named(name: str)

Remove a switch by name.

remove()

Remove the switch from the world. Clean up the monitor.

classmethod stop()

Stop monitoring the state of all switches.

check_state(state: str) → bool

Test the state of one of the switch’s properties.

Parameters:

state – the state to test for, should be one of self.on or self.off

mciwb.threads

Functions to manage threads.

Each thread maintains its own Client object for parallel execution of Minecraft Server functions. The 1st Client object is created on the main thread and then passed to new_thread.

mciwb.threads.new_thread(client: Client, target, name: str) → Thread

Create a thread with its own RCON Client connection stored in thread local storage

mciwb.threads.set_client(client: Client) → None

Set the client for this thread. Use this when the client object has been created outside of new_thread.

mciwb.threads.get_client() → Client

retrieve the client for the current thread

mciwb.threads.get_thread_name() → str

retrieve the name of the current thread. This is the name that was passed to new_thread.