Blocks Place, read, copy and bulk-edit blocks. edit() is the fast path for large builds.
mc. setblock (
x: int,
y: int,
z: int,
block_name: str,
block_state: dict = None ,
nbt: dict = None ,
) -> intSet a block at the specified coordinates
Parameters block_namestr required Block type (e.g., "minecraft:stone")
block_statedict = None Optional block state properties (e.g., {"facing": "north", "half": "bottom"}). Any vanilla property of the block is accepted.
nbtdict = None Optional block entity data. Only two keys are applied: "CustomName" (plain text, for containers such as chests) and "Text1"-"Text4" (sign lines). Other keys are ignored.
Returns int 1 if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If command execution failsExample >>> mc. setblock ( 100 , 64 , 200 , "minecraft:stone" )
1
>>> mc. setblock ( 100 , 64 , 200 , "minecraft:oak_stairs" , block_state= { "facing" : "north" , "half" : "bottom" } )
1
>>> mc. setblock ( 100 , 64 , 200 , "minecraft:chest" , nbt= { "CustomName" : "My Chest" } )
1 Copy Sent as setblock client.py line 228
mc. getblock ( x: int, y: int, z: int) -> strGet the block type at the specified coordinates
Returns str Block type (e.g., "minecraft:stone")
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If command execution failsExample >>> mc. getblock ( 100 , 64 , 200 )
'minecraft:stone' Copy Sent as getblock client.py line 281
mc. getblocks (
x1: int,
y1: int,
z1: int,
x2: int,
y2: int,
z2: int,
) -> List [ List [ List [ str] ] ] Get all blocks in a rectangular region as a 3D array
Returns a 3D array in the same [x][y][z] format used by edit(), so you can read a region, modify it, and write it back with edit().
Parameters x1int required Starting X coordinate
y1int required Starting Y coordinate
z1int required Starting Z coordinate
x2int required Ending X coordinate
y2int required Ending Y coordinate
z2int required Ending Z coordinate
Returns List[List[List[str]]] 3D list of block types [x][y][z] (e.g., "minecraft:stone")
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If command execution failsExamples >>> blocks = mc. getblocks ( 100 , 64 , 200 , 102 , 65 , 202 )
>>> print ( blocks[ 0 ] [ 0 ] [ 0 ] )
'minecraft:stone' Copy >>> # Read, modify, and write back
>>> blocks = mc. getblocks ( 100 , 64 , 200 , 110 , 68 , 210 )
>>> for x in range ( len ( blocks) ) :
... for y in range ( len ( blocks[ 0 ] ) ) :
... for z in range ( len ( blocks[ 0 ] [ 0 ] ) ) :
... if blocks[ x] [ y] [ z] == "minecraft:stone" :
... blocks[ x] [ y] [ z] = "minecraft:diamond_block"
>>> mc. edit ( min ( 100 , 110 ) , min ( 64 , 68 ) , min ( 200 , 210 ) , blocks) Copy Sent as getblocks client.py line 308
mc. fill (
x1: int,
y1: int,
z1: int,
x2: int,
y2: int,
z2: int,
block_name: str,
) -> intFill a region with the specified block
Parameters x1int required Starting X coordinate
y1int required Starting Y coordinate
z1int required Starting Z coordinate
x2int required Ending X coordinate
y2int required Ending Y coordinate
z2int required Ending Z coordinate
block_namestr required Block type (e.g., "minecraft:glass")
Returns int Number of blocks affected
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If command execution failsExample >>> mc. fill ( 100 , 64 , 200 , 110 , 74 , 210 , "minecraft:glass" ) # 11x11x11, corners inclusive
1331 Copy Sent as fill client.py line 358
mc. clone (
x1: int,
y1: int,
z1: int,
x2: int,
y2: int,
z2: int,
dest_x: int,
dest_y: int,
dest_z: int,
) -> intClone a region of blocks to a new location
Parameters x1int required Source region start X coordinate
y1int required Source region start Y coordinate
z1int required Source region start Z coordinate
x2int required Source region end X coordinate
y2int required Source region end Y coordinate
z2int required Source region end Z coordinate
dest_xint required Destination X coordinate
dest_yint required Destination Y coordinate
dest_zint required Destination Z coordinate
Returns int Number of blocks cloned
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If region too large (max 32768 blocks)Example >>> mc. clone ( 0 , 64 , 0 , 10 , 74 , 10 , 20 , 64 , 0 ) # 11x11x11, corners inclusive
1331 Copy Sent as clone client.py line 1106
mc. edit (
x: int,
y: int,
z: int,
blocks: List [ List [ List ] ] ,
) -> intBulk edit a 3D region of blocks with high performance (like WorldEdit)
This method allows you to quickly place large numbers of different blocks in a single operation, making it ideal for constructing large buildings and structures. It's much faster than using setblock repeatedly.
Parameters xint required Starting X coordinate
yint required Starting Y coordinate
zint required Starting Z coordinate
blocksList[List[List]] required 3D array of blocks [x][y][z], where each element can be:
str: Block name (e.g., "minecraft:stone") None: Skip this position (leave unchanged) dict: Complex block with state and NBT:{
"block" : "minecraft:chest" ,
"block_state" : { "facing" : "north" } , # Optional
"nbt" : { "CustomName" : "Storage" } # Optional, same keys as setblock()
} Doors, beds and tall plants can be given as one entry (the lower half or the bed's foot); the other half is added automatically unless the array sets that position itself. Returns int Number of blocks placed (None entries and added halves are not counted)
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid block data or coordinatesExamples >>> # Simple 2x2x2 cube of stone and glass
>>> blocks = [
... [ [ "stone" , "glass" ] , [ "stone" , "glass" ] ] ,
... [ [ "stone" , "glass" ] , [ "stone" , "glass" ] ]
... ]
>>> mc. edit ( 100 , 64 , 200 , blocks)
8 Copy >>> # Mixed mode with simple and complex blocks
>>> blocks = [
... [ [ None , "stone" ] , [ "glass" , None ] ] ,
... [ [ {
... "block" : "minecraft:chest" ,
... "block_state" : { "facing" : "north" } ,
... "nbt" : { "CustomName" : "Loot" }
... } , "stone" ] , [ "diamond_block" , "gold_block" ] ]
... ]
>>> mc. edit ( 100 , 64 , 200 , blocks)
6 Copy >>> # Build a 10x5x10 house with different materials
>>> import numpy as np
>>> blocks = np. full ( ( 10 , 5 , 10 ) , None , dtype= object)
>>> # Floor
>>> blocks[ : , 0 , : ] = "stone"
>>> # Walls
>>> blocks[ 0 , : , : ] = "cobblestone"
>>> blocks[ 9 , : , : ] = "cobblestone"
>>> blocks[ : , : , 0 ] = "cobblestone"
>>> blocks[ : , : , 9 ] = "cobblestone"
>>> # Roof
>>> blocks[ : , 4 , : ] = "oak_planks"
>>> mc. edit ( 100 , 64 , 200 , blocks. tolist ( ) )
308 Copy Sent as bulkEdit client.py line 1147
Players Find and teleport players, change game modes, give items, set spawn points and advancements.
mc. getPos ( username: str) -> List [ int] Get the position of a player
Parameters usernamestr required Player username
Returns List[int] List of [x, y, z] coordinates
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If command execution fails (e.g., player not found)Example >>> mc. getPos ( "Steve" )
[100, 64, 200] Copy Sent as getPos client.py line 398
mc. teleport (
username: str,
x: float,
y: float,
z: float,
yaw: float = None ,
pitch: float = None ,
) -> boolTeleport player to coordinates
Parameters usernamestr required Player username
xfloat required X coordinate
yfloat required Y coordinate
zfloat required Z coordinate
yawfloat = None Optional rotation yaw angle
pitchfloat = None Optional rotation pitch angle
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found or teleport failsExample >>> mc. teleport ( "Steve" , 100 , 64 , 200 )
True
>>> mc. teleport ( "Steve" , 100 , 64 , 200 , yaw= 90.0 , pitch= 0.0 )
True Copy Sent as teleport client.py line 421
mc. gamemode ( username: str, mode: str) -> boolChange player gamemode
Parameters usernamestr required Player username
modestr required Gamemode (survival, creative, adventure, spectator)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found or invalid gamemodeExample >>> mc. gamemode ( "Steve" , "creative" )
True
>>> mc. gamemode ( "Steve" , "survival" )
True Copy Sent as gamemode client.py line 460
mc. give ( username: str, item: str, amount: int = 1 ) -> boolGive items to player
Parameters usernamestr required Player username
itemstr required Item type (e.g., "minecraft:diamond")
amountint = 1 Quantity (1-64, default: 1)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found, invalid item, or amount out of rangeExample >>> mc. give ( "Steve" , "minecraft:diamond" , 10 )
True
>>> mc. give ( "Steve" , "diamond_sword" )
True Copy Sent as give client.py line 551
mc. spawnpoint (
username: str,
x: float = None ,
y: float = None ,
z: float = None ,
) -> boolSet a player's spawn point
Parameters usernamestr required Player username
xfloat = None X coordinate (default: player's current position)
yfloat = None Y coordinate (default: player's current position)
zfloat = None Z coordinate (default: player's current position)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not foundExample >>> mc. spawnpoint ( "Steve" , 100 , 64 , 200 )
True
>>> mc. spawnpoint ( "Steve" ) # Use current position
True Copy Sent as spawnpoint client.py line 1698
mc. advancement (
username: str,
action: str,
advancement_key: str,
) -> boolGrant, revoke, or query player advancements
Parameters usernamestr required Player username
actionstr required Action ("grant", "revoke", or "query")
advancement_keystr required Advancement key (e.g., "story/mine_stone", "minecraft:story/iron_tools")
Returns bool True if successful (for grant/revoke), or bool for query (whether completed)
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found or invalid advancementExample >>> mc. advancement ( "Steve" , "grant" , "story/mine_stone" )
True
>>> mc. advancement ( "Steve" , "query" , "story/mine_stone" )
True Copy Sent as advancement client.py line 2265
Effects & experience Status effects, experience points and levels, and enchantments.
mc. effect (
username: str,
effect_type: str,
duration: int = 30 ,
amplifier: int = 0 ,
hide_particles: bool = False ,
) -> boolApply a potion effect to a player
Parameters usernamestr required Player username
effect_typestr required Effect type (e.g., "speed", "strength", "minecraft:invisibility")
durationint = 30 Duration in seconds (default: 30)
amplifierint = 0 Effect amplifier/level (0 = level I, 1 = level II, etc.)
hide_particlesbool = False Whether to hide effect particles
Returns bool True if the effect was applied successfully
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found or invalid effect typeExample >>> mc. effect ( "Steve" , "speed" , duration= 60 , amplifier= 1 )
True
>>> mc. effect ( "Steve" , "minecraft:invisibility" , hide_particles= True )
True Copy Sent as effect client.py line 1311
mc. clearEffect (
username: str,
effect_type: str = None ,
) -> boolRemove potion effects from a player
Parameters usernamestr required Player username
effect_typestr = None Specific effect to remove, or None to remove all effects
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found or invalid effect typeExample >>> mc. clearEffect ( "Steve" , "speed" )
True
>>> mc. clearEffect ( "Steve" ) # Remove all effects
True Copy Sent as clearEffect client.py line 1345
mc. experience (
username: str,
action: str,
amount: int = 0 ,
target: str = 'points' ,
) -> dictManage player experience points and levels
Parameters usernamestr required Player username
actionstr required Action to perform ("add", "set", or "query")
amountint = 0 Amount of XP points or levels. Note that "set" with target="points" only sets the progress bar within the current level (amount / points needed for the next level, clamped to 0-1).
targetstr = 'points' Target type ("points" or "levels")
Returns dict Dictionary with keys: level, points (total XP, from level and progress), progress
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found or invalid actionExample >>> mc. experience ( "Steve" , "add" , 100 )
{'level': 7, 'points': 100, 'progress': 0.43}
>>> mc. experience ( "Steve" , "set" , 10 , target= "levels" )
{'level': 10, 'points': 172, 'progress': 0.43}
>>> mc. experience ( "Steve" , "query" )
{'level': 10, 'points': 172, 'progress': 0.43} Copy Sent as experience client.py line 1398
mc. enchant (
username: str,
enchantment: str,
level: int = 1 ,
) -> boolEnchant the item in a player's main hand
Parameters usernamestr required Player username
enchantmentstr required Enchantment name (e.g., "sharpness", "minecraft:unbreaking")
levelint = 1 Enchantment level (default: 1)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found, not holding item, or invalid enchantmentExample >>> mc. enchant ( "Steve" , "sharpness" , 5 )
True Copy Sent as enchant client.py line 2155
Inventory Read and change inventory slots.
mc. clear (
username: str,
item: str = None ,
max_count: int = - 1 ,
) -> intClear items from a player's inventory
Parameters usernamestr required Player username
itemstr = None Item type to clear (e.g., "diamond"), or None to clear all
max_countint = -1 Maximum number of items to remove (-1 for all)
Returns int Number of items removed
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found or invalid item typeExample >>> mc. clear ( "Steve" ) # Clear entire inventory
64
>>> mc. clear ( "Steve" , "diamond" , 10 ) # Remove up to 10 diamonds
10 Copy Sent as clear client.py line 1371
mc. getItem ( username: str, slot: int) -> dictGet item information from a player's inventory slot
Parameters usernamestr required Player username
slotint required Inventory slot number (0-35 for main inventory)
Returns dict Dictionary with item, amount, and (if any) enchantments. For an empty slot it is {'amount': 0} (the "item" key is left out).
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found or invalid slotExample >>> mc. getItem ( "Steve" , 0 )
{'item': 'minecraft:diamond_sword', 'amount': 1, 'enchantments': {'sharpness': 5}} Copy Sent as getItem client.py line 2182
mc. setItem (
username: str,
slot: int,
item: str,
amount: int = 1 ,
) -> boolSet an item in a player's inventory slot
Parameters usernamestr required Player username
slotint required Inventory slot number (0-35 for main inventory)
itemstr required Item type (e.g., "diamond_sword", "minecraft:golden_apple")
amountint = 1 Item count (default: 1)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found, invalid slot, or invalid itemExample >>> mc. setItem ( "Steve" , 0 , "diamond_sword" )
True Copy Sent as setItem client.py line 2205
World settings Time, weather, difficulty, game rules, spawn, world border and chunk loading.
mc. time ( action: str, value: int = None ) -> intControl world time
Parameters actionstr required Action to perform (set, add, query)
valueint = None Time value (0-24000) for set/add actions
Returns int Current world time
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid action or value out of rangeExample >>> mc. time ( "set" , 1000 )
1000
>>> mc. time ( "add" , 6000 )
7000
>>> mc. time ( "query" )
7000 Copy Sent as time client.py line 487
mc. weather ( condition: str, duration: int = None ) -> boolControl world weather
Parameters conditionstr required Weather condition (clear, rain, thunder)
durationint = None Optional duration in seconds
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid conditionExample >>> mc. weather ( "clear" )
True
>>> mc. weather ( "rain" , duration= 600 )
True
>>> mc. weather ( "thunder" , duration= 300 )
True Copy Sent as weather client.py line 519
mc. difficulty ( level: str) -> boolSet the world difficulty
Parameters levelstr required Difficulty level ("peaceful", "easy", "normal", "hard")
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid difficulty levelExample >>> mc. difficulty ( "hard" )
True Copy Sent as difficulty client.py line 1435
mc. gamerule ( rule: str, value: str = None ) -> strGet or set a game rule
Parameters rulestr required Game rule name (e.g., "keep_inventory", "mob_griefing"; legacy camelCase names like "keepInventory" are also accepted)
valuestr = None Value to set, or None to query current value
Returns str Current value of the game rule as string
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid game ruleExample >>> mc. gamerule ( "doDaylightCycle" , "false" )
'false'
>>> mc. gamerule ( "keep_inventory" )
'false' Copy Sent as gamerule client.py line 1456
mc. defaultgamemode ( mode: str) -> boolSet the default game mode for new players
Parameters modestr required Game mode (survival, creative, adventure, spectator)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid game modeExample >>> mc. defaultgamemode ( "creative" )
True Copy Sent as defaultgamemode client.py line 2571
mc. setworldspawn ( x: int, y: int, z: int) -> boolSet the world spawn location
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If setting spawn failsExample >>> mc. setworldspawn ( 0 , 64 , 0 )
True Copy Sent as setworldspawn client.py line 1729
mc. worldborder (
action: str,
value: float = None ,
time: int = None ,
x: float = None ,
z: float = None ,
) -> dictManage the world border
Parameters actionstr required Action ("get", "set", "center", "add", "damage", "warning")
valuefloat = None Size value for set/add, damage amount for damage, warning distance for warning
timeint = None Transition time in seconds for set/add, warning time for warning
xfloat = None X coordinate for center action
zfloat = None Z coordinate for center action
Returns dict Dictionary with border information
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid action or parametersExample >>> mc. worldborder ( "get" )
{'size': 59999968.0, 'center_x': 0.0, 'center_z': 0.0, 'damage_amount': 0.2, 'damage_buffer': 5.0, 'warning_distance': 5, 'warning_time': 15}
>>> mc. worldborder ( "set" , value= 1000 , time= 10 )
{'size': 1000.0}
>>> mc. worldborder ( "center" , x= 100 , z= 200 )
{'center_x': 100.0, 'center_z': 200.0} Copy Sent as worldborder client.py line 1752
mc. forceload ( action: str, x: int, z: int) -> boolForce-load or unload chunks
Parameters actionstr required Action ("add", "remove", "query")
xint required Block X coordinate (will be converted to chunk coordinate)
zint required Block Z coordinate (will be converted to chunk coordinate)
Returns bool True/False for add/remove/query operations
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid actionExample >>> mc. forceload ( "add" , 100 , 200 )
True
>>> mc. forceload ( "query" , 100 , 200 )
True
>>> mc. forceload ( "remove" , 100 , 200 )
True Copy Sent as forceload client.py line 1790
Chat, sound & particles Messages, titles, sounds and particle effects.
mc. say ( message: str) -> boolBroadcast a message to all players
Parameters messagestr required Message to broadcast
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If broadcast failsExample >>> mc. say ( "Hello everyone!" )
True Copy Sent as say client.py line 1483
mc. tell ( username: str, message: str) -> boolSend a private message to a player
Parameters usernamestr required Player username
messagestr required Message to send
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not foundExample >>> mc. tell ( "Steve" , "Hello Steve!" )
True Copy Sent as tell client.py line 1504
mc. tellraw ( username: str, json_text: str) -> boolSend a raw JSON text message to a player
The request is run as the vanilla ``tellraw`` command, so ``username`` may also be a target selector such as "@a".
Parameters usernamestr required Player username (or a target selector)
json_textstr required JSON text component as a string (not a dict or list)
Returns bool True once the command was dispatched (an unknown player is only reported in the server log)
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found or invalid JSONExample >>> mc. tellraw ( "Steve" , '{"text":"Hello","color":"gold","bold":true}' )
True Copy Sent as tellraw client.py line 1526
mc. title (
username: str,
title: str = '' ,
subtitle: str = '' ,
fade_in: int = 10 ,
stay: int = 70 ,
fade_out: int = 20 ,
) -> boolDisplay a title on a player's screen
Parameters usernamestr required Player username
titlestr = '' Main title text
subtitlestr = '' Subtitle text
fade_inint = 10 Fade in time in ticks (default: 10)
stayint = 70 Stay time in ticks (default: 70)
fade_outint = 20 Fade out time in ticks (default: 20)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not foundExample >>> mc. title ( "Steve" , "Welcome!" , "Enjoy your stay" )
True Copy Sent as title client.py line 1552
mc. playsound (
username: str,
sound: str,
source: str = 'master' ,
x: float = None ,
y: float = None ,
z: float = None ,
volume: float = 1.0 ,
pitch: float = 1.0 ,
) -> boolPlay a sound for a player
Parameters usernamestr required Player username
soundstr required Sound name (e.g., "entity.experience_orb.pickup")
sourcestr = 'master' Sound source category (master, music, record, weather, block, hostile, neutral, player, ambient, voice)
xfloat = None X coordinate (default: player position)
yfloat = None Y coordinate (default: player position)
zfloat = None Z coordinate (default: player position)
volumefloat = 1.0 Volume (default: 1.0)
pitchfloat = 1.0 Pitch (default: 1.0)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not found or invalid soundExample >>> mc. playsound ( "Steve" , "entity.experience_orb.pickup" )
True
>>> mc. playsound ( "Steve" , "block.note_block.harp" , x= 100 , y= 64 , z= 200 , pitch= 1.5 )
True Copy Sent as playsound client.py line 1586
mc. stopsound (
username: str,
sound: str = None ,
source: str = None ,
) -> boolStop sounds for a player
Parameters usernamestr required Player username
soundstr = None Specific sound to stop, or None to stop all sounds
sourcestr = None Sound category of ``sound`` (only used together with ``sound``; without a sound, all sounds stop)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If player not foundExample >>> mc. stopsound ( "Steve" ) # Stop all sounds
True
>>> mc. stopsound ( "Steve" , "minecraft:music.creative" )
True Copy Sent as stopsound client.py line 1628
mc. particle (
particle_type: str,
x: float,
y: float,
z: float,
count: int = 1 ,
dx: float = 0 ,
dy: float = 0 ,
dz: float = 0 ,
speed: float = 0 ,
) -> boolSpawn particles at a location
Particles that need extra data (such as "dust", "block" or "item") are not supported and raise CommandError.
Parameters particle_typestr required Particle type (e.g., "flame", "heart", "minecraft:smoke")
xfloat required X coordinate
yfloat required Y coordinate
zfloat required Z coordinate
countint = 1 Number of particles (default: 1)
dxfloat = 0 X spread (default: 0)
dyfloat = 0 Y spread (default: 0)
dzfloat = 0 Z spread (default: 0)
speedfloat = 0 Particle speed (default: 0)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid particle typeExample >>> mc. particle ( "flame" , 100 , 65 , 200 , count= 50 , dx= 1 , dy= 1 , dz= 1 , speed= 0.1 )
True Copy Sent as particle client.py line 1658
Entities Summon entities and control their position, motion, AI, health, riding and attributes.
mc. summon (
entity_type: str,
x: float,
y: float,
z: float,
) -> strSummon an entity at coordinates
Parameters entity_typestr required Entity type (e.g., "minecraft:zombie", "pig")
xfloat required X coordinate
yfloat required Y coordinate
zfloat required Z coordinate
Returns str Entity UUID as string
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid entity type or coordinatesExample >>> uuid = mc. summon ( "minecraft:zombie" , 100 , 64 , 200 )
>>> uuid = mc. summon ( "pig" , 150 , 70 , 250 ) Copy Sent as summon client.py line 580
mc. kill ( selector: str) -> intRemove entities from the world
Only three selector forms are understood (vanilla selectors such as "@e[type=zombie]" or UUIDs are rejected). "all" and entity types act on the first (main) world and remove at most 1000 entities per call.
Parameters selectorstr required "all" (every non-player entity, including dropped items, armor stands and item frames), an entity type such as "zombie", or "player:username" (sets that player's health to 0)
Returns int Number of entities killed
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid selector or player not foundExample >>> mc. kill ( "all" )
42
>>> mc. kill ( "zombie" )
5
>>> mc. kill ( "player:Steve" )
1 Copy Sent as kill client.py line 609
mc. getEntityPos ( entity_uuid: str) -> dictGet the position of an entity by UUID
Parameters entity_uuidstr required Entity UUID string
Returns dict Position dictionary with keys: x, y, z, yaw, pitch
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found or invalid UUIDExample >>> uuid = mc. summon ( "zombie" , 100 , 64 , 200 )
>>> pos = mc. getEntityPos ( uuid)
>>> print ( f"Position: ({pos['x']}, {pos['y']}, {pos['z']})" ) Copy Sent as getEntityPos client.py line 642
mc. getEntityStatus ( entity_uuid: str) -> dictGet complete status information of an entity
Parameters entity_uuidstr required Entity UUID string
Returns dict Status dictionary containing: - uuid: Entity UUID - type: Entity type (e.g., "minecraft:zombie") - custom_name: Custom name (key omitted when the entity has none) - is_valid: Whether entity is valid - is_dead: Whether entity is dead - position: {x, y, z} coordinates - velocity: {x, y, z} velocity vector - world: World name - health: Current health (LivingEntity only, key omitted otherwise) - max_health: Maximum health (LivingEntity only, key omitted otherwise) - has_ai: Whether AI is enabled (LivingEntity only, key omitted otherwise) The server leaves out keys whose value would be null, so use status.get("custom_name") for the optional ones.
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found or invalid UUIDExample >>> uuid = mc. summon ( "zombie" , 100 , 64 , 200 )
>>> status = mc. getEntityStatus ( uuid)
>>> print ( f"Health: {status['health']}/{status['max_health']}" )
>>> print ( f"AI enabled: {status['has_ai']}" ) Copy Sent as getEntityStatus client.py line 666
mc. teleportEntity (
entity_uuid: str,
x: float,
y: float,
z: float,
yaw: float = None ,
pitch: float = None ,
) -> boolTeleport an entity to specified coordinates
Parameters entity_uuidstr required Entity UUID string
xfloat required Target X coordinate
yfloat required Target Y coordinate
zfloat required Target Z coordinate
yawfloat = None Optional rotation yaw angle
pitchfloat = None Optional rotation pitch angle
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found or teleport failsExample >>> uuid = mc. summon ( "pig" , 100 , 64 , 200 )
>>> mc. teleportEntity ( uuid, 110 , 70 , 210 )
True
>>> mc. teleportEntity ( uuid, 120 , 64 , 220 , yaw= 90.0 , pitch= 0.0 )
True Copy Sent as teleportEntity client.py line 705
mc. setEntityVelocity (
entity_uuid: str,
vx: float,
vy: float,
vz: float,
) -> boolSet the velocity of an entity
Parameters entity_uuidstr required Entity UUID string
vxfloat required X velocity component (blocks/tick, clamped to ±10)
vyfloat required Y velocity component (blocks/tick, clamped to ±10)
vzfloat required Z velocity component (blocks/tick, clamped to ±10)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not foundExample >>> uuid = mc. summon ( "pig" , 100 , 64 , 200 )
>>> # Make the pig jump
>>> mc. setEntityVelocity ( uuid, 0 , 1.0 , 0 )
True
>>> # Push the pig forward
>>> mc. setEntityVelocity ( uuid, 0.5 , 0.2 , 0.5 )
True Copy Sent as setEntityVelocity client.py line 752
mc. setEntityRotation (
entity_uuid: str,
yaw: float,
pitch: float,
) -> boolSet the rotation (facing direction) of an entity
Parameters entity_uuidstr required Entity UUID string
yawfloat required Horizontal rotation angle (0=south, 90=west, 180=north, 270=east)
pitchfloat required Vertical rotation angle (-90=up, 0=horizontal, 90=down)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If the entity is not found, or a player's rotation was blocked (for example by another plugin)Example >>> uuid = mc. summon ( "zombie" , 100 , 64 , 200 )
>>> # Face north
>>> mc. setEntityRotation ( uuid, 180.0 , 0.0 )
True
>>> # Look up
>>> mc. setEntityRotation ( uuid, 180.0 , - 45.0 )
True Copy Sent as setEntityRotation client.py line 792
mc. setEntityAI ( entity_uuid: str, enabled: bool) -> boolEnable or disable AI for a living entity
When AI is disabled, the entity will not move, attack, or perform any autonomous behavior (like a statue).
Parameters entity_uuidstr required Entity UUID string
enabledbool required True to enable AI, False to disable
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found or not a LivingEntityExample >>> uuid = mc. summon ( "zombie" , 100 , 64 , 200 )
>>> # Freeze the zombie (disable AI)
>>> mc. setEntityAI ( uuid, False )
True
>>> # Re-enable AI
>>> mc. setEntityAI ( uuid, True )
True Copy Sent as setEntityAI client.py line 830
mc. setEntityTarget (
entity_uuid: str,
target_uuid: str = None ,
) -> boolSet or clear the attack target of a mob entity
Parameters entity_uuidstr required UUID of the mob entity
target_uuidstr = None UUID of the target entity (must be a LivingEntity), or None to clear the target
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found, not a Mob, or target is invalidExample >>> zombie = mc. summon ( "zombie" , 100 , 64 , 200 )
>>> villager = mc. summon ( "villager" , 105 , 64 , 200 )
>>> # Make zombie target the villager
>>> mc. setEntityTarget ( zombie, villager)
True
>>> # Clear the target
>>> mc. setEntityTarget ( zombie, None )
True Copy Sent as setEntityTarget client.py line 863
mc. removeEntity ( entity_uuid: str) -> boolRemove an entity from the world
Parameters entity_uuidstr required Entity UUID string
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found or is a playerExample >>> uuid = mc. summon ( "pig" , 100 , 64 , 200 )
>>> mc. removeEntity ( uuid)
True Copy Sent as removeEntity client.py line 900
mc. damage (
entity_uuid: str,
amount: float,
source_uuid: str = None ,
) -> boolDeal damage to an entity
Parameters entity_uuidstr required Target entity UUID
amountfloat required Damage amount
source_uuidstr = None Optional UUID of the entity dealing damage
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found or not a LivingEntityExample >>> uuid = mc. summon ( "zombie" , 100 , 64 , 200 )
>>> mc. damage ( uuid, 5.0 )
True Copy Sent as damage client.py line 1817
mc. ride (
passenger_uuid: str,
vehicle_uuid: str = None ,
) -> boolMake an entity ride another entity, or dismount
Parameters passenger_uuidstr required UUID of the passenger entity
vehicle_uuidstr = None UUID of the vehicle entity, or None to dismount
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not foundExample >>> pig = mc. summon ( "pig" , 100 , 64 , 200 )
>>> zombie = mc. summon ( "zombie" , 100 , 64 , 200 )
>>> mc. ride ( zombie, pig) # Zombie rides the pig
True
>>> mc. ride ( zombie) # Zombie dismounts
True Copy Sent as ride client.py line 2507
mc. attribute (
entity_uuid: str,
attribute_name: str,
action: str = 'get' ,
value: float = None ,
) -> dictGet or set entity attributes
Parameters entity_uuidstr required Entity UUID
attribute_namestr required Attribute name (e.g., "MAX_HEALTH", "MOVEMENT_SPEED", "ATTACK_DAMAGE")
actionstr = 'get' Action ("get" or "set")
valuefloat = None Value to set (required for "set" action)
Returns dict Dictionary with base_value and value
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found or invalid attributeExample >>> mc. attribute ( uuid, "MAX_HEALTH" )
{'base_value': 20.0, 'value': 20.0}
>>> mc. attribute ( uuid, "MAX_HEALTH" , action= "set" , value= 40.0 )
{'base_value': 40.0, 'value': 40.0} Copy Sent as attribute client.py line 2122
Equipment & tags Armor and held items, plus scoreboard tags for grouping entities.
mc. getEntityEquipment ( entity_uuid: str) -> dictGet the equipment of a living entity
Parameters entity_uuidstr required Entity UUID string
Returns dict Equipment dictionary with these keys (item ids such as "minecraft:diamond_helmet"); empty slots are left out: - helmet - chestplate - leggings - boots - main_hand - off_hand
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found or doesn't support equipmentExample >>> uuid = mc. summon ( "zombie" , 100 , 64 , 200 )
>>> equipment = mc. getEntityEquipment ( uuid)
>>> print ( f"Helmet: {equipment.get('helmet')}" ) # None if no helmet Copy Sent as getEntityEquipment client.py line 924
mc. setEntityEquipment (
entity_uuid: str,
equipment: dict,
drop_chances: dict = None ,
) -> boolSet the equipment of a living entity
Parameters entity_uuidstr required Entity UUID string
equipmentdict required Dictionary of equipment slots to set. Keys can be:
helmet: Item name (e.g., "diamond_helmet") chestplate: Item name leggings: Item name boots: Item name main_hand: Item name off_hand: Item name drop_chancesdict = None Optional dictionary of drop chances (0.0-1.0) for each slot
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found or doesn't support equipmentExample >>> uuid = mc. summon ( "zombie" , 100 , 64 , 200 )
>>> mc. setEntityEquipment ( uuid, {
... "helmet" : "diamond_helmet" ,
... "chestplate" : "diamond_chestplate" ,
... "main_hand" : "diamond_sword"
... } , drop_chances= { "helmet" : 0.1 , "main_hand" : 0.5 } )
True Copy Sent as setEntityEquipment client.py line 955
mc. addTag ( entity_uuid: str, tag: str) -> boolAdd a scoreboard tag to an entity
Parameters entity_uuidstr required Entity UUID
Returns bool True if the tag was added (False if already had it)
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not foundExample >>> uuid = mc. summon ( "zombie" , 100 , 64 , 200 )
>>> mc. addTag ( uuid, "boss" )
True Copy Sent as addTag client.py line 1962
mc. removeTag ( entity_uuid: str, tag: str) -> boolRemove a scoreboard tag from an entity
Parameters entity_uuidstr required Entity UUID
Returns bool True if the tag was removed
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not foundExample >>> mc. removeTag ( uuid, "boss" )
True Copy Sent as removeTag client.py line 1985
mc. getTags ( entity_uuid: str) -> List [ str] Get all scoreboard tags of an entity
Parameters entity_uuidstr required Entity UUID
Returns List[str] List of tag strings
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not foundExample >>> mc. getTags ( uuid)
['boss', 'enemy'] Copy Sent as getTags client.py line 2007
Villagers Professions, levels and custom trades.
mc. getVillagerData ( villager_uuid: str) -> dictGet villager profession, level, and trade information
Parameters villager_uuidstr required Villager entity UUID string
Returns dict Dictionary containing: - profession: Villager profession name (e.g., "LIBRARIAN") - level: Villager level (1-5) - trades: List of trade dictionaries, each containing: - buy1: {"item": str, "amount": int} - buy2: {"item": str, "amount": int} (only present when the trade has a second ingredient) - sell: {"item": str, "amount": int} - uses: Current number of uses - max_uses: Maximum number of uses
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found or not a villagerExample >>> uuid = mc. summon ( "villager" , 100 , 64 , 200 )
>>> data = mc. getVillagerData ( uuid)
>>> print ( f"Profession: {data['profession']}" )
>>> print ( f"Number of trades: {len(data['trades'])}" ) Copy Sent as getVillagerData client.py line 999
mc. setVillagerProfession (
villager_uuid: str,
profession: str,
) -> boolSet a villager's profession
Parameters villager_uuidstr required Villager entity UUID string
professionstr required Profession name. Valid values are: ARMORER, BUTCHER, CARTOGRAPHER, CLERIC, FARMER, FISHERMAN, FLETCHER, LEATHERWORKER, LIBRARIAN, MASON, NITWIT, NONE, SHEPHERD, TOOLSMITH, WEAPONSMITH
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found, not a villager, or invalid professionExample >>> uuid = mc. summon ( "villager" , 100 , 64 , 200 )
>>> mc. setVillagerProfession ( uuid, "LIBRARIAN" )
True Copy Sent as setVillagerProfession client.py line 1033
mc. setVillagerTrades (
villager_uuid: str,
trades: list,
) -> boolSet custom trades for a villager (replaces all existing trades)
Parameters villager_uuidstr required Villager entity UUID string
tradeslist required List of trade definitions. Each trade is a dictionary with:
buy1: {"item": str, "amount": int} - First ingredient (required) buy2: {"item": str, "amount": int} - Second ingredient (optional) sell: {"item": str, "amount": int} - Result item (required) max_uses: Maximum number of uses (default: 10) experience_reward: Whether to give XP (default: True) Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If entity not found, not a villager, or invalid trade dataExample >>> uuid = mc. summon ( "villager" , 100 , 64 , 200 )
>>> mc. setVillagerProfession ( uuid, "LIBRARIAN" )
>>> mc. setVillagerTrades ( uuid, [
... {
... "buy1" : { "item" : "emerald" , "amount" : 10 } ,
... "sell" : { "item" : "diamond_sword" , "amount" : 1 } ,
... "max_uses" : 5
... } ,
... {
... "buy1" : { "item" : "emerald" , "amount" : 5 } ,
... "buy2" : { "item" : "book" , "amount" : 1 } ,
... "sell" : { "item" : "enchanted_book" , "amount" : 1 } ,
... "max_uses" : 10
... }
... ] )
True Copy Sent as setVillagerTrades client.py line 1062
Scoreboards, teams & boss bars Objectives, scores, display slots, teams and boss bars.
mc. addObjective (
name: str,
criteria: str,
display_name: str = None ,
) -> boolAdd a scoreboard objective
Parameters namestr required Objective name
criteriastr required Criteria (e.g., "dummy", "playerKillCount")
display_namestr = None Display name (default: same as name)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If objective already existsExample >>> mc. addObjective ( "kills" , "playerKillCount" , "Player Kills" )
True Copy Sent as addObjective client.py line 1844
mc. removeObjective ( name: str) -> boolRemove a scoreboard objective
Parameters namestr required Objective name
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If objective not foundExample >>> mc. removeObjective ( "kills" )
True Copy Sent as removeObjective client.py line 1870
mc. setScore (
objective: str,
player: str,
score: int,
) -> boolSet a player's score for an objective
Parameters objectivestr required Objective name
playerstr required Player name or entity name
scoreint required Score value
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If objective not foundExample >>> mc. setScore ( "kills" , "Steve" , 10 )
True Copy Sent as setScore client.py line 1891
mc. getScore ( objective: str, player: str) -> intGet a player's score for an objective
Parameters objectivestr required Objective name
playerstr required Player name or entity name
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If objective not foundExample >>> mc. getScore ( "kills" , "Steve" )
10 Copy Sent as getScore client.py line 1914
mc. setDisplaySlot (
slot: str,
objective: str = None ,
) -> boolSet which objective is displayed in a display slot
Parameters slotstr required Display slot ("below_name", "sidebar", "player_list")
objectivestr = None Objective name, or None to clear the slot
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid slot or objective not foundExample >>> mc. setDisplaySlot ( "sidebar" , "kills" )
True
>>> mc. setDisplaySlot ( "sidebar" ) # Clear sidebar
True Copy Sent as setDisplaySlot client.py line 1936
mc. team (
action: str,
name: str = None ,
members: List [ str] = None ,
option: str = None ,
value: str = None ,
display_name: str = None ,
) -> dictManage scoreboard teams
Parameters actionstr required Action ("add", "remove", "join", "leave", "modify", "list")
namestr = None Team name (required for most actions)
membersList[str] = None List of player names (for join/leave)
optionstr = None Option name for modify (displayname, color, friendlyfire, seefriendlyinvisibles, prefix, suffix)
valuestr = None Value for modify action
display_namestr = None Display name for add action
Returns dict Dictionary with team information
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If team not found or invalid actionExample >>> mc. team ( "add" , "red_team" , display_name= "Red Team" )
{'name': 'red_team'}
>>> mc. team ( "join" , "red_team" , members= [ "Steve" , "Alex" ] )
{'added': 2}
>>> mc. team ( "modify" , "red_team" , option= "color" , value= "RED" )
{'modified': True}
>>> mc. team ( "list" )
{'teams': [...]} Copy Sent as team client.py line 2028
mc. bossbar (
action: str,
bar_id: str,
title: str = None ,
color: str = None ,
style: str = None ,
progress: float = None ,
visible: bool = None ,
username: str = None ,
) -> dictManage boss bars
Bars are kept in the plugin's memory (not vanilla /bossbar ids), so they disappear when the server restarts. On "add", an unknown color or style falls back to WHITE / SOLID; on "set" it raises CommandError.
Parameters actionstr required Action ("add", "remove", "set", "addplayer", "removeplayer", "get", "list")
bar_idstr required Boss bar ID (required for every action; any value works for "list")
titlestr = None Bar title (for add/set)
colorstr = None Bar color (WHITE, PINK, BLUE, RED, GREEN, YELLOW, PURPLE) (for add/set)
stylestr = None Bar style (SOLID, SEGMENTED_6, SEGMENTED_10, SEGMENTED_12, SEGMENTED_20) (for add/set)
progressfloat = None Progress value 0.0-1.0 (for add/set)
visiblebool = None Visibility (for add/set)
usernamestr = None Player name (for addplayer/removeplayer)
Returns dict Dictionary with boss bar information
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If boss bar not found or invalid actionExample >>> mc. bossbar ( "add" , "my_bar" , title= "Boss Fight" , color= "RED" )
{'id': 'my_bar'}
>>> mc. bossbar ( "addplayer" , "my_bar" , username= "Steve" )
{'added': True}
>>> mc. bossbar ( "set" , "my_bar" , progress= 0.5 )
{'updated': True} Copy Sent as bossbar client.py line 2072
World generation Locate structures, generate loot, paint biomes and place features, structures and templates.
mc. locate (
structure: str,
x: float = None ,
z: float = None ,
) -> dictLocate the nearest structure
Searches the first (main) world within 100 chunks of the start point.
Parameters structurestr required Structure key (e.g., "village_plains", "minecraft:desert_pyramid", "ancient_city"). Structure tags such as "village" are not accepted.
xfloat = None Search from X coordinate (default: world spawn)
zfloat = None Search from Z coordinate (default: world spawn)
Returns dict Dictionary with found (bool) and x, y, z if found. The coordinates point at the structure's chunk; y is not a ground height (usually 0).
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid structure typeExample >>> mc. locate ( "village_plains" )
{'found': True, 'x': 16, 'y': 0, 'z': 112} Copy Sent as locate client.py line 2235
mc. loot (
loot_table: str,
x: float,
y: float,
z: float,
) -> intGenerate loot from a loot table and drop it at a location
Parameters loot_tablestr required Loot table name (e.g., "chests/simple_dungeon")
xfloat required X coordinate
yfloat required Y coordinate
zfloat required Z coordinate
Returns int Number of items generated
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid loot tableExample >>> mc. loot ( "chests/simple_dungeon" , 100 , 64 , 200 )
5 Copy Sent as loot client.py line 2295
mc. fillbiome (
x1: int,
y1: int,
z1: int,
x2: int,
y2: int,
z2: int,
biome: str,
filter_biome: str = None ,
) -> boolFill a region with a specific biome
Runs the vanilla ``fillbiome`` command. The region must be loaded, and vanilla rejects very large regions; such failures (like "That position is not loaded") are only reported in the server log.
Parameters x1int required Start X coordinate
y1int required Start Y coordinate
z1int required Start Z coordinate
x2int required End X coordinate
y2int required End Y coordinate
z2int required End Z coordinate
biomestr required Target biome (e.g., "minecraft:plains")
filter_biomestr = None Only replace this biome (optional)
Returns bool True once the command was dispatched
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If the biome name is invalidExample >>> mc. fillbiome ( 100 , 60 , 200 , 115 , 75 , 215 , "minecraft:desert" )
True Copy Sent as fillbiome client.py line 2322
mc. placeFeature (
feature: str,
x: int = None ,
y: int = None ,
z: int = None ,
) -> boolPlace a configured feature at a location
Runs the vanilla ``place feature`` command. The target chunk must be loaded; vanilla failures are only reported in the server log.
Parameters featurestr required Feature name (e.g., "minecraft:oak")
xint = None X coordinate (optional)
yint = None Y coordinate (optional)
zint = None Z coordinate (optional)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid featureExample >>> mc. placeFeature ( "minecraft:oak" , 100 , 64 , 200 )
True Copy Sent as placeFeature client.py line 2361
mc. placeStructure (
structure: str,
x: int = None ,
y: int = None ,
z: int = None ,
) -> boolPlace a structure at a location
Runs the vanilla ``place structure`` command. The target chunk must be loaded; vanilla failures are only reported in the server log.
Parameters structurestr required Structure name (e.g., "minecraft:village_plains")
xint = None X coordinate (optional)
yint = None Y coordinate (optional)
zint = None Z coordinate (optional)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid structureExample >>> mc. placeStructure ( "minecraft:village_plains" , 100 , 64 , 200 )
True Copy Sent as placeStructure client.py line 2393
mc. placeJigsaw (
pool: str,
target: str,
max_depth: int,
x: int = None ,
y: int = None ,
z: int = None ,
) -> boolPlace a jigsaw structure pool at a location
Runs the vanilla ``place jigsaw`` command. The target chunk must be loaded; vanilla failures are only reported in the server log.
Parameters poolstr required Jigsaw pool name
targetstr required Target name
max_depthint required Maximum depth (1-20)
xint = None X coordinate (optional)
yint = None Y coordinate (optional)
zint = None Z coordinate (optional)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid pool or parametersExample >>> mc. placeJigsaw ( "minecraft:village/plains/houses" , "minecraft:empty" , 7 , 100 , 64 , 200 )
True Copy Sent as placeJigsaw client.py line 2425
mc. placeTemplate (
template: str,
x: int = None ,
y: int = None ,
z: int = None ,
rotation: str = 'none' ,
mirror: str = 'none' ,
integrity: float = 1.0 ,
seed: int = 0 ,
) -> boolPlace a structure template at a location
Runs the vanilla ``place template`` command. The target chunk must be loaded; vanilla failures are only reported in the server log.
Parameters templatestr required Template name
xint = None X coordinate (optional)
yint = None Y coordinate (optional)
zint = None Z coordinate (optional)
rotationstr = 'none' Rotation (none, clockwise_90, 180, counterclockwise_90)
mirrorstr = 'none' Mirror mode (none, front_back, left_right)
integrityfloat = 1.0 Structure integrity 0.0-1.0 (default: 1.0)
seedint = 0 Random seed for integrity (default: 0)
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If invalid templateExample >>> mc. placeTemplate ( "my_house" , 100 , 64 , 200 , rotation= "clockwise_90" )
True Copy Sent as placeTemplate client.py line 2463
Server Run any command, list online players and spread players across the map.
mc. exec ( command: str) -> boolExecute any Minecraft command on the server
A universal command executor that can run any Minecraft command. Useful for commands not yet wrapped as dedicated methods.
The command runs as the server console. Its output (including vanilla errors such as "No player was found") only appears in the server log.
Parameters commandstr required The command to execute (with or without leading /)
Returns bool True if the server found and ran the command (even if the command itself reported a failure), False if the command does not exist
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If command execution failsExample >>> mc. exec ( "seed" )
True
>>> mc. exec ( "/say Hello World" )
True Copy Sent as exec client.py line 1281
mc. list ( ) -> dictGet list of online players
Returns dict Dictionary with online_count, max_players, and players list
Raises ConnectionError If connection failsAuthenticationError If authentication failsExample >>> mc. list ( )
{'online_count': 2, 'max_players': 20, 'players': [{'name': 'Steve', ...}]} Copy Sent as list client.py line 2592
mc. spreadplayers (
center_x: float,
center_z: float,
spread_distance: float,
max_range: float,
usernames: List [ str] ,
) -> boolSpread players randomly around a center point
Runs the vanilla ``spreadplayers`` command (respectTeams = false); vanilla failures are only reported in the server log.
Parameters center_xfloat required Center X coordinate
center_zfloat required Center Z coordinate
spread_distancefloat required Minimum distance between players
max_rangefloat required Maximum distance from center
usernamesList[str] required List of player usernames to spread
Returns bool True if successful
Raises ConnectionError If connection failsAuthenticationError If authentication failsCommandError If players not found or invalid parametersExample >>> mc. spreadplayers ( 0 , 0 , 10 , 100 , [ "Steve" , "Alex" ] )
True Copy Sent as spreadplayers client.py line 2535