Minescript v3.0 docs
Table of contents:
Previous version: v2.1
Latest version: latest
In-game commands
Command basics
Minescript commands are available from the in-game chat console. They’re
similar to Minecraft commands that start with a slash (/
), but Minescript
commands start with a backslash (\
) instead.
Python scripts in the minescript folder (within the minecraft folder)
can be run as commands from the in-game chat by placing a backslash (\
)
before the script name and dropping the .py
from the end of the filename.
E.g. a Python script minecraft/minescript/build_fortress.py
can be run as a
Minescript command by entering \build_fortress
in the in-game chat. If the
in-game chat is hidden, you can display it by pressing \
, similar to
pressing t
or /
in vanilla Minecraft. Parameters can be passed to
Minescript script commands if the Python script supports command-line
parameters. (See example at Script input below).
Minescript commands that take a sequence of X Y Z
parameters can take tilde
syntax to specify locations relative to the local player, e.g. ~ ~ ~
or ~-1
~2 ~-3
. Alternatively, params can be specified as $x
, $y
, and $z
for the
local player’s x, y, or z coordinate, respectively. ($
syntax is particularly
useful to specify coordinates that don’t appear as 3 consecutive X Y Z
coordinates.)
Optional command parameters below are shown in square brackets like this: [EXAMPLE]. (But leave out the brackets when entering actual commands.)
General commands
ls
Usage: \ls
List all available Minescript commands, including both Minescript built-in commands and Python scripts in the minescript folder.
help
Usage: \help NAME
Prints documentation for the given script or command name.
Since: v1.19.2
copy
Usage: \copy X1 Y1 Z1 X2 Y2 Z2 [LABEL] [no_limit]
Copies blocks within the rectangular box from (X1, Y1, Z1) to (X2, Y2, Z2), similar to the coordinates passed to the /fill command. LABEL is optional, allowing a set of blocks to be named.
By default, attempts to copy a region covering more than 1600 chunks are
disallowed. This limit can be relaxed by passing no_limit
.
See \paste.
paste
Usage: \paste X Y Z [LABEL]
Pastes blocks at location (X, Y, Z) that were previously copied via \copy. When the optional param LABEL is given, blocks are pasted from the most recent copy command with the same LABEL given, otherwise blocks are pasted from the most recent copy command with no label given.
Note that \copy and \paste can be run within different worlds to copy a region from one world into another.
See \copy.
jobs
Usage: \jobs
Lists the currently running Minescript jobs.
suspend
Usage: \suspend [JOB_ID]
Suspends currently running Minescript job or jobs. If JOB_ID is specified, the job with that integer ID is suspended. Otherwise, all currently running Minescript jobs are suspended.
See \resume.
z
Usage: \z [JOB_ID]
Alias for \suspend
.
resume
Usage: \resume [JOB_ID]
Resumes currently suspended Minescript job or jobs. If JOB_ID is specified, the job with that integer ID is resumed if currently suspended. If JOB_ID is not specified, all currently suspended Minescript jobs are resumed.
See \suspend.
killjob
Usage: \killjob JOB_ID
Kills the currently running or suspended Minescript job corresponding to JOB_ID. The special value -1 can be specified to kill all currently running or suspended Minescript jobs.
undo
Usage: \undo
Undoes all the /setblock
and /fill
commands run by the last Minescript
command by restoring the blocks present beforehand. This is useful if a
Minescript command accidentally destroyed a build and you’d like to revert to
the state of your build before the last command. \undo
can be run multiple
times to undo the build changes from multiple recent Minescript commands.
Note: Some block state may be lost when undoing a Minescript command, such as commands specified within command blocks and items in chests.
Advanced commands
minescript_commands_per_cycle
Usage: \minescript_commands_per_cycle NUMBER
Specifies the number of Minescript-generated Minecraft commands to run per Minescript processing cycle. The higher the number, the faster the script will run.
Note: Setting this value too high will make Minecraft less responsive and possibly crash.
Default is 15.
minescript_ticks_per_cycle
Usage: \minescript_ticks_per_cycle NUMBER
Specifies the number of Minecraft game ticks to wait per Minecraft processing cycle. The lower the number, down to a minimum of 1, the faster the script will run.
Note: Setting this value too low will make Minecraft less responsive and possibly crash.
Default is 3.
minescript_incremental_command_suggestions
Usage: \minescript_incremental_command_suggestions BOOL
Enables or disables printing of incremental command suggestions to the in-game chat as the user types a Minescript command.
Default is false.
Since: v2.0 (in prior versions, incremental command suggestions were unconditionally enabled)
Python API
Script input
Parameters can be passed from Minecraft as input to a Python script. For
example, consider this Python script located at
minecraft/minescript/build_fortress.py
:
import sys
def BuildFortress(width, height, length):
...
width = sys.argv[1]
height = sys.argv[2]
length = sys.argv[3]
# Or more succinctly:
# width, height, length = sys.argv[1:]
BuildFortress(width, height, length)
The above script can be run from the Minecraft in-game chat as:
\build_fortress 100 50 200
That command passes parameters that set width
to 100
, height
to 50
, and
length
to 200
.
Script output
Minescript Python scripts can write outputs using sys.stdout
and
sys.stderr
, or they can use functions defined in minescript.py
(see
echo
, chat
, and execute
). The
minescript.py
functions are recommended going forward, but output via
sys.stdout
and sys.stderr
are provided for backward compatibility with
earlier versions of Minescript.
Printing to standard output (sys.stdout
) outputs text to the Minecraft chat
as if entered by the user:
# Sends a chat message that's visible to
# all players in the world:
print("hi, friends!")
# Since Minescript v2.0 this can be written as:
import minescript
minescript.chat("hi, friends!")
# Runs a command to set the block under the
# current player to yellow concrete (assuming
# you have permission to run commands):
print("/setblock ~ ~-1 ~ yellow_concrete")
# Since Minescript v2.1 this can be written as:
minescript.execute("/setblock ~ ~-1 ~ yellow_concrete")
When a script prints to standard error (sys.stderr
), the output text is
printed to the Minecraft chat, but is visible only to you:
# Prints a message to the in-game chat that's
# visible only to you:
print("Note to self...", file=sys.stderr)
# Since Minescript v2.0 this can be written as:
minescript.echo("Note to self...")
minescript module
Usage: import minescript # from Python script
User-friendly API for scripts to make function calls into the Minescript mod. This module should be imported by other scripts and not run directly.
execute
Usage: execute(command: str)
Executes the given command.
If command
doesn’t already start with a slash or backslash, automatically
prepends a slash. Ignores leading and trailing whitespace, and ignores empty
commands.
Note: This was named exec
in Minescript 2.0. The old name is no longer
available in v3.0.
Since: v2.1
echo
Usage: echo(message: Any)
Echoes message to the chat.
The echoed message is visible only to the local player.
Since: v2.0
chat
Usage: chat(message: str)
Sends the given message to the chat.
If message
starts with a slash or backslash, automatically prepends a space
so that the message is sent as a chat and not executed as a command. Ignores
empty messages.
Since: v2.0
log
Usage: log(message: str) -> bool
Sends the given message to latest.log.
Args:
message
: string to send to the log
Returns:
True
ifmessage
was logged successfully.
Since: v3.0
screenshot
Usage: screenshot(filename=None) -> bool
Takes a screenshot, similar to pressing the F2 key.
Args:
filename
: if specified, screenshot filename relative to the screenshots directory; “.png” extension is added to the screenshot file if it doesn’t already have a png extension.
Returns:
True
is successful
Since: v2.1
flush
Usage: flush()
Wait for all previously issued script commands from this job to complete.
Since: v2.1
player_name
Usage: player_name() -> str
Gets the local player’s name.
Since: v2.1
player_position
Usage: player_position(done_callback=None) -> List[float]
Gets the local player’s position.
Args:
done_callback
: if given, return immediately and calldone_callback(return_value)
asynchronously whenreturn_value
is ready
Returns:
- if
done_callback
isNone
, returns player’s position as [x: float, y: float, z: float]
player_hand_items
Usage: player_hand_items(done_callback=None) -> List[Dict[str, Any]]
Gets the items in the local player’s hands.
Args:
done_callback
: if given, return immediately and calldone_callback(return_value)
asynchronously whenreturn_value
is ready
Returns:
- If
done_callback
isNone
, returns items in player’s hands as a list of items where each item is a dict
:{"item": str, "count": int}
, plus"nbt": str
if the item has NBT data; main-hand item is at list index 0, off-hand item at index 1.
Since: v2.0
player_inventory
Usage: player_inventory(done_callback=None) -> List[Dict[str, Any]]
Gets the items in the local player’s inventory.
Args:
done_callback
: if given, return immediately and calldone_callback(return_value)
asynchronously whenreturn_value
is ready
Returns:
- If
done_callback
isNone
, returns items in player’s inventory as list of items where each item is a dict
:{"item": str, "count": int, "slot": int}
, plus"nbt": str
if an item has NBT data and"selected": True
for the item selected in the player’s main hand.
Update in v3.0:
Introduced "slot"
and "selected"
attributes in the returned
dict, and "nbt"
is populated only when NBT data is present. (In prior
versions, "nbt"
was always populated, with a value of null
when NBT data
was absent.)
Since: v2.0
player_inventory_slot_to_hotbar
Usage: player_inventory_slot_to_hotbar(slot: int, done_callback=None) -> int
Swaps an inventory item into the hotbar.
Args:
slot
: inventory slot (9 or higher) to swap into the hotbardone_callback
: if given, return immediately and calldone_callback(return_value)
asynchronously whenreturn_value
is ready
Returns:
- If
done_callback
isNone
, returns the hotbar slot (0-8) that the inventory item was swapped into
Since: v3.0
player_inventory_select_slot
Usage: player_inventory_select_slot(slot: int, done_callback=None) -> int
Selects the given slot within the player’s hotbar.
Args:
slot
: hotbar slot (0-8) to select in the player’s handdone_callback
: if given, return immediately and calldone_callback(return_value)
asynchronously whenreturn_value
is ready
Returns:
- If
done_callback
isNone
, returns the previously selected hotbar slot
Since: v3.0
player_press_forward
Usage: player_press_forward(pressed: bool)
Starts/stops moving the local player forward, simulating press/release of the ‘w’ key.
Args:
pressed
: ifTrue
, go forward, otherwise stop doing so
Since: v2.1
player_press_backward
Usage: player_press_backward(pressed: bool)
Starts/stops moving the local player backward, simulating press/release of the ‘s’ key.
Args:
pressed
: ifTrue
, go backward, otherwise stop doing so
Since: v2.1
player_press_left
Usage: player_press_left(pressed: bool)
Starts/stops moving the local player to the left, simulating press/release of the ‘a’ key.
Args:
pressed
: ifTrue
, move to the left, otherwise stop doing so
Since: v2.1
player_press_right
Usage: player_press_right(pressed: bool)
Starts/stops moving the local player to the right, simulating press/release of the ‘d’ key.
Args:
pressed
: ifTrue
, move to the right, otherwise stop doing so
Since: v2.1
player_press_jump
Usage: player_press_jump(pressed: bool)
Starts/stops the local player jumping, simulating press/release of the space key.
Args:
pressed
: ifTrue
, jump, otherwise stop doing so
Since: v2.1
player_press_sprint
Usage: player_press_sprint(pressed: bool)
Starts/stops the local player sprinting, simulating press/release of the left control key.
Args:
pressed
: ifTrue
, sprint, otherwise stop doing so
Since: v2.1
player_press_sneak
Usage: player_press_sneak(pressed: bool)
Starts/stops the local player sneaking, simulating press/release of the left shift key.
Args:
pressed
: ifTrue
, sneak, otherwise stop doing so
Since: v2.1
player_press_pick_item
Usage: player_press_pick_item(pressed: bool)
Starts/stops the local player picking an item, simulating press/release of the middle mouse button.
Args:
pressed
: ifTrue
, pick an item, otherwise stop doing so
Since: v2.1
player_press_use
Usage: player_press_use(pressed: bool)
Starts/stops the local player using an item or selecting a block, simulating press/release of the right mouse button.
Args:
pressed
: ifTrue
, use an item, otherwise stop doing so
Since: v2.1
player_press_attack
Usage: player_press_attack(pressed: bool)
Starts/stops the local player attacking or breaking a block, simulating press/release of the left mouse button.
Args:
pressed
: ifTrue
, press attack, otherwise stop doing so
Since: v2.1
player_press_swap_hands
Usage: player_press_swap_hands(pressed: bool)
Starts/stops moving the local player swapping hands, simulating press/release of the ‘f’ key.
Args:
pressed
: ifTrue
, swap hands, otherwise stop doing so
Since: v2.1
player_press_drop
Usage: player_press_drop(pressed: bool)
Starts/stops the local player dropping an item, simulating press/release of the ‘q’ key.
Args:
pressed
: ifTrue
, drop an item, otherwise stop doing so
Since: v2.1
player_orientation
Usage: player_orientation()
Gets the local player’s orientation.
Returns:
- (yaw: float, pitch: float) as angles in degrees
Since: v2.1
player_set_orientation
Usage: player_set_orientation(yaw: float, pitch: float)
Sets the local player’s orientation.
Args:
yaw
: degrees rotation of the local player’s orientation around the y axispitch
: degrees rotation of the local player’s orientation from the x-z plane
Returns:
- True if successful
Since: v2.1
player_get_targeted_block
Usage: player_get_targeted_block(max_distance: float = 20)
Gets info about the nearest block, if any, in the local player’s crosshairs.
Args:
max_distance
: max distance from local player to look for blocks
Returns:
- [[x, y, z], distance, side, block_description] if the local player has a
block in their crosshairs within
max_distance
,None
otherwise.distance
(float) is calculated from the player to the targeted block;side
(str) is the direction that the targeted side of the block is facing (e.g."east"
);block_description
(str) describes the targeted block.
Since: v3.0
players
Usage: players()
Gets a list of nearby players and their attributes.
Returns:
- List of players where each player is represented as a dict:
{"name": str, "type": str, "position": [float, float, float], "yaw": float, "pitch": float, "velocity": [float, float, float]}
Since: v2.1
entities
Usage: entities()
Gets a list of nearby entities and their attributes.
Returns:
- List of entities where each entity is represented as a dict:
{"name": str, "type": str, "position": [float, float, float], "yaw": float, "pitch": float, "velocity": [float, float, float]}
Since: v2.1
getblock
Usage: getblock(x: int, y: int, z: int, done_callback=None)
Gets the type of block at position (x, y, z).
Args:
done_callback
: if given, return immediately and calldone_callback(return_value)
asynchronously whenreturn_value
is ready
Returns:
- if
done_callback
isNone
, returns the block type at (x, y, z) as a string
getblocklist
Usage: getblocklist(positions: List[List[int]], done_callback=None)
Gets the types of block at the specified [x, y, z] positions.
Args:
done_callback
: if given, return immediately and calldone_callback(return_value)
asynchronously whenreturn_value
is ready
Returns:
- if
done_callback
isNone
, returns the block types at given positions as list of strings
Since: v2.1
await_loaded_region
Usage: await_loaded_region(x1: int, z1: int, x2: int, z2: int, done_callback=None)
Notifies the caller when the region from (x1, z1) to (x2, z2) is loaded.
Args:
done_callback
: if given, return immediately and calldone_callback(return_value)
asynchronously whenreturn_value
is ready
Returns:
- if
done_callback
isNone
, returnsTrue
when the requested region is fully loaded.
Examples:
[1] Don’t do any work until the region is done loading (synchronous / blocking call):
minescript.echo("About to wait for region to load...")
# Load all chunks within (x, z) bounds (0, 0) and (320, 160):
minescript.await_loaded_region(0, 0, 320, 160)
minescript.echo("Region finished loading.")
[2] Continue doing work on the main thread while the region loads in the background (asynchronous / non-blocking call):
import minescript
import threading
lock = threading.Lock()
def on_region_loaded(loaded):
if loaded:
minescript.echo("Region loaded ok.")
else:
minescript.echo("Region failed to load.")
lock.release()
# Acquire the lock, to be released later by on_region_loaded().
lock.acquire()
# Calls on_region_loaded(...) when region finishes
# loading all chunks within (x, z) bounds (0, 0)
# and (320, 160):
minescript.await_loaded_region(
0, 0, 320, 160, on_region_loaded)
minescript.echo("Do other work while region loads...")
minescript.echo("Now wait for region to finish loading...")
lock.acquire()
minescript.echo("Do more work now that region finished loading...")
register_chat_message_listener
Usage: register_chat_message_listener(listener: Callable[[str], None])
Registers a listener for receiving chat messages. One listener allowed per job.
Listener receives both incoming and outgoing chat messages.
Args:
listener
: callable that repeatedly accepts a string representing chat messages
Since: v2.0
See also:
register_chat_message_interceptor()
for swallowing outgoing chat messages
unregister_chat_message_listener
Usage: unregister_chat_message_listener()
Unegisters a chat message listener, if any, for the currently running job.
Returns:
True
if successfully unregistered a listener.
Since: v2.0
register_chat_message_interceptor
Usage: register_chat_message_interceptor(interceptor: Callable[[str], None])
Registers an interceptor for swallowing chat messages.
An interceptor swallows outgoing chat messages, typically for use in rewriting outgoing chat messages by calling minecraft.chat(str), e.g. to decorate or post-process outgoing messages automatically before they’re sent to the server. Only one interceptor is allowed at a time within a Minecraft instance.
Args:
interceptor
: callable that repeatedly accepts a string representing chat messages
Since: v2.1
See also:
register_chat_message_listener()
for non-destructive listening of chat messages
unregister_chat_message_interceptor
Usage: unregister_chat_message_interceptor()
Unegisters the chat message interceptor, if one is currently registered.
Returns:
True
if successfully unregistered an interceptor.
Since: v2.1
BlockPos
Tuple representing (x: int, y: int, z: int)
position in block space.
Rotation
Tuple of 9 int
values representing a flattened, row-major 3×3 rotation matrix.
Rotations
Common rotations for use with BlockPack
and BlockPacker
methods.
Since: v3.0
Rotations.IDENTITY
Effectively no rotation.
Rotations.X_90
Rotate 90 degrees about the x axis.
Rotations.X_180
Rotate 180 degrees about the x axis.
Rotations.X_270
Rotate 270 degrees about the x axis.
Rotations.Y_90
Rotate 90 degrees about the y axis.
Rotations.Y_180
Rotate 180 degrees about the y axis.
Rotations.Y_270
Rotate 270 degrees about the y axis.
Rotations.Z_90
Rotate 90 degrees about the z axis.
Rotations.Z_180
Rotate 180 degrees about the z axis.
Rotations.Z_270
Rotate 270 degrees about the z axis.
Rotations.INVERT_X
Invert the x coordinate (multiply by -1).
Rotations.INVERT_Y
Invert the y coordinate (multiply by -1).
Rotations.INVERT_Z
Invert the z coordinate (multiply by -1).
combine_rotations
Usage: combine_rotations(rot1: Rotation, rot2: Rotation, /) -> Rotation
Combines two rotation matrices into a single rotation matrix.
Since: v3.0
BlockPack
BlockPack is an immutable and serializable collection of blocks.
A blockpack can be read from or written to worlds, files, and serialized bytes. Although blockpacks are immutable and preserve position and orientation of blocks, they can be rotated and offset when read from or written to worlds.
For a mutable collection of blocks, see BlockPacker
.
Since: v3.0
BlockPack.read_world
Usage: @classmethod BlockPack.read_world(pos1: BlockPos, pos2: BlockPos, *, rotation: Rotation = None, offset: BlockPos = None, comments: Dict[str, str] = {}, safety_limit: bool = True) -> BlockPack
Creates a blockpack from blocks in the world within a rectangular volume.
Args:
pos1, pos2
: opposing corners of a rectangular volume from which to read world blocksrotation
: rotation matrix to apply to block coordinates read from worldoffset
: offset to apply to block coordiantes (applied after rotation)comments
: key, value pairs to include in the new blockpacksafety_limit
: ifTrue
, fail if requested volume spans more than 1600 chunks
Returns:
- a new BlockPack containing blocks read from the world
Raises:
BlockPackException
if blockpack cannot be read
BlockPack.read_file
Usage: @classmethod BlockPack.read_file(filename: str, *, relative_to_cwd=False) -> BlockPack
Reads a blockpack from a file.
Args:
filename
: name of file relative to minescript/blockpacks dir unless it’s an absolute path (“.zip” is automatically appended to filename if it does not end with that extension)relative_to_cwd
: ifTrue
, relative filename is taken to be relative to Minecraft dir
Returns:
- a new BlockPack containing blocks read from the file
Raises:
BlockPackException
if blockpack cannot be read
BlockPack.import_data
Usage: @classmethod BlockPack.import_data(base64_data: str) -> BlockPack
Creates a blockpack from base64-encoded serialized blockpack data.
Args:
base64_data
: base64-encoded string containing serialization of blockpack data.
Returns:
- a new BlockPack containing blocks read from the base64-encoded data
Raises:
BlockPackException
if blockpack cannot be read
BlockPack.block_bounds
Usage: BlockPack.block_bounds() -> (BlockPos, BlockPos)
Returns min and max bounding coordinates of blocks in this BlockPack.
Raises:
BlockPackException
if blockpack cannot be accessed
BlockPack.comments
Usage: BlockPack.comments() -> Dict[str, str]
Returns comments stored in this BlockPack.
Raises:
BlockPackException
if blockpack cannot be accessed
Raises:
BlockPackException
if blockpack operation fails
BlockPack.write_world
Usage: BlockPack.write_world(*, rotation: Rotation = None, offset: BlockPos = None)
Writes blocks from this BlockPack into the current world. Requires setblock, fill commands.
Args:
rotation
: rotation matrix to apply to block coordinates before writing to worldoffset
: offset to apply to block coordiantes (applied after rotation)
Raises:
BlockPackException
if blockpack operation fails
BlockPack.write_file
Usage: BlockPack.write_file(filename: str, *, relative_to_cwd=False)
Writes this BlockPack to a file.
Args:
filename
: name of file relative to minescript/blockpacks dir unless it’s an absolute path (“.zip” is automatically appended to filename if it does not end with that extension)relative_to_cwd
: ifTrue
, relative filename is taken to be relative to Minecraft dir
Raises:
BlockPackException
if blockpack operation fails
BlockPack.export_data
Usage: BlockPack.export_data() -> str
Serializes this BlockPack into a base64-encoded string.
Returns:
- a base64-encoded string containing this blockpack’s data
Raises:
BlockPackException
if blockpack operation fails
BlockPack.__del__
Usage: del blockpack
Frees this BlockPack to be garbage collected.
Raises:
BlockPackException
if blockpack operation fails
BlockPacker
BlockPacker is a mutable collection of blocks.
Blocks can be added to a blockpacker by calling setblock(...)
, fill(...)
,
and/or add_blockpack(...)
. To serialize blocks or write them to a world, a
blockpacker can be “packed” by calling pack() to create a compact snapshot of
the blocks contained in the blockpacker in the form of a new BlockPack. A
blockpacker continues to store the same blocks it had before being packed,
and more blocks can be added thereafter.
For a collection of blocks that is immutable and serializable, see BlockPack
.
Since: v3.0
BlockPacker.__init__
Usage: BlockPacker()
Creates a new, empty blockpacker.
BlockPacker.setblock
Usage: BlockPacker.setblock(pos: BlockPos, block_type: str)
Sets a block within this BlockPacker.
Args:
pos
: position of a block to setblock_type
: block descriptor to set
Raises:
BlockPackerException
if blockpacker operation fails
BlockPacker.fill
Usage: BlockPacker.fill(pos1: BlockPos, pos2: BlockPos, block_type: str)
Fills blocks within this BlockPacker.
Args:
pos1, pos2
: coordinates of opposing corners of a rectangular volume to fillblock_type
: block descriptor to fill
Raises:
BlockPackerException
if blockpacker operation fails
BlockPacker.add_blockpack
Usage: BlockPacker.add_blockpack(blockpack: BlockPack, *, rotation: Rotation = None, offset: BlockPos = None)
Adds the blocks within a BlockPack into this BlockPacker.
Args:
blockpack
: BlockPack from which to copy blocksrotation
: rotation matrix to apply to block coordinates before adding to blockpackeroffset
: offset to apply to block coordiantes (applied after rotation)
Raises:
BlockPackerException
if blockpacker operation fails
BlockPacker.pack
Usage: BlockPacker.pack(*, comments: Dict[str, str] = {}) -> BlockPack
Packs blocks within this BlockPacker into a new BlockPack.
Args:
comments
: key, value pairs to include in the new BlockPack
Returns:
- a new BlockPack containing a snapshot of blocks from this BlockPacker
Raises:
BlockPackerException
if blockpacker operation fails
BlockPacker.__del__
Usage: del blockpacker
Frees this BlockPacker to be garbage collected.
Raises:
BlockPackerException
if blockpacker operation fails