Documentation

Minescript v4.0 docs

View docs for all versions of Minescript on GitHub.

Table of contents:

• In-game commands
  • Command basics
  • Built-in commands
  • Advanced commands
• Configuration
• Python API
  • Script input
  • Script output
  • Script functions
  • Script tasks
  • Async script functions
  • minescript module

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.)

Built-in 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

eval

Usage: \eval PYTHON_CODE [LINE2 [LINE3 ...]]

Executes PYTHON_CODE (and optional subsequent lines LINE2, LINE3, etc) as either a Python expression (code that can appear on the right-hand side of an assignment, in which case the value is echoed to the chat screen) or Python statements (e.g. a for loop).

Functions from minescript.py are available automatically without qualification.

Examples:

• Print information about nearby entities to the chat screen:

\eval "entities()"

• Print the names of nearby entities to the chat screen:

\eval "for e in entities(): echo(e['name'])"

• Import time module, sleep 3 seconds, and take a screenshot:

\eval "import time" "time.sleep(3)" "screenshot()"

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.

Configuration

The minescript directory contains a configuration file named config.txt. Lines of text in config.txt can take the following forms:

• Lines containing configuration variables of the form: NAME=VALUE, e.g. python="/usr/bin/python3".
• Lines ending with a backslash (\) are interpreted as being joined with the next line. Multiple consecutive lines ending in \ are considered the same line of configuration together with the subsequent line.
• Lines beginning with # are comments that have no effect on Minescript behavior.
• Blank lines have no effect on Minescript behavior.

Config variable names:

• autorun[WORLD NAME] – command to run when entering a world named WORLD NAME (since v3.1)

  • The special name * indicates that the command should be run when entering all worlds, e.g. autorun[*]=eval 'echo(f"Hello, {world_info().name}!")' that welcomes you with message when connecting to a world.
  • Multiple autorun[...] config lines can be specified for the same world, or for *, in which case all matching commands are run concurrently.
  • A single autorun[...] config line can execute multiple commands in sequence by separating commands with a semicolon (;), e.g. the following would first print info about the world followed by the names of the 10 nearest entities: autorun[*]=eval "world_info()"; eval "[e.name for e in entities(sort='nearest', limit=10)]"
  • python – file location of the Python interpreter (default for Windows is "%userprofile%\AppData\Local\Microsoft\WindowsApps\python3.exe", and "/usr/bin/python3" for other operating systems)
  • command – configuration for customizing invocations of scripts or executables from Minecraft commands. command can be specified multiple times for different filename extensions. For example, to execute jar files such as foo.jar from the Minescript command \foo: command = { "extension": ".jar", "command": [ "/usr/bin/java", "-jar", "{command}", "{args}" ], "environment": [ "FIRST_ENV_VAR=1234", "SECOND_ENV_VAR=2468" ] } environment is optional, allowing environment variables to be passed to scripts/executables. When configuring execution of Python scripts, remember to set PYTHON_PATH in environment.
  • command_path – sets the command path for executing scripts/executables from Minescript commands. Entries that aren’t absolute paths are relative to the minescript directory. Paths on Windows are separated by ;, whereas paths on other operating systems are separated by :. The default is equivalent to the minescript directory and system/exec within it.
  • escape_command_double_quotes – if true, escape double quotes that appear in {args} in the command field of a command config entry. Defaults to true for Windows, false for other operating systems.
  • max_commands_per_cycle – number of Minescript-generated Minecraft commands to run per Minescript processing cycle. The higher the number, the faster the script will run. Default is 15. (Note: Setting this value too high will make Minecraft less responsive and possibly crash.)
  • command_cycle_deadline_usecs – threshold in microseconds beyond which Minescript stops executing commands for the given execution cycle. Default is 10000 (10 milliseconds). A command that runs over the threshold continues to run to completion, but no more commands will be executed in that cycle.
  • ticks_per_cycle – 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. Default is 1 since v3.2. (Previously, default was 3.)
  • incremental_command_suggestions – enables or disables printing of incremental command suggestions to the in-game chat as the user types a Minescript command. Default is false.
  • report_job_success_threshold_millis – report on-screen that a script job has exited successfully if it has run for more than this duration in milliseconds; default value is 3000 (3 seconds); 0 always reports; -1 never reports; exits of failed script jobs are always reported (since v4.0)
  • debug_output – if true, enable debug output to logs/latest.log. Default is false.
  • minescript_on_chat_received_event – if true, Minescript executes chat messages that start with "You whisper to ..." that contain a message starting with a backslash (\), e.g. from a command block executing [execute as maxuser run tell maxuser \eval 1+2]. Default is false.
  • secondary_enter_key_code – The enter key (key code 257, called return on Macs) is the primary key for terminating commands in the chat. secondary_enter_key_code is a customizable secondary key which can also terminate commands. Default is 335 (KEY_KP_ENTER). See GLFW Keyboard key tokens for a list of key codes.
  • stderr_chat_ignore_pattern – regular expression for ignoring lines of output from stderr of scripts. Default is the empty string: "^$". This can be useful for Python installations that have spammy stderr output when running from Minescript.

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...")

Script functions

Script functions imported from minescript.py can be called as functions, as tasks, or asynchronously.

When called directly, e.g. minescript.screenshot("my_screenshot.png"), script functions are implemented in Java and typically return after the function has finished executing in Java. (A handful of script functions return immediately while Java processing continues in the background: execute, echo, echo_json, chat, and log.)

There are 3 Java executors on which script functions can run:

1. minescript.tick_loop: the game tick loop which runs once even game tick (20 times per second, which is a cycle time of 50 milliseconds)
2. minescript.render_loop: executed when a frame is rendered (typically around 60 frames per second, which is a cycle time of 15-20 milliseconds, but can vary significantly based on game performance)
3. minescript.script_loop: executor that processes script functions as quickly as possible, but not on the rendering thread, so may lead to instability or even crash the game due to lack of thread-safety in Minecraft Java code (cycle time is typically less than 1 millisecond)

The Java executor can be selected for a specific script function or within a specific script context. The selection of executor for a script function is determined by the following priority, from highest to lowest:

1. Required executor for this function, if there is one. This is set with the function’s set_required_executor method, e.g. minescript.player.set_required_executor(minescript.script_loop). No required executor is set by default.
2. Executor set by the script context using a with block, e.g. with minescript.script_loop: position = minescript.player().position # processed by the high-speed script loop ...
3. Default executor for this function, if there is one. This is set with the function’s set_default_executor method, e.g. minescript.player.set_default_executor(minescript.script_loop). No default executor is set for individual script functions by default.
4. Default executor for the current script job. This is set with the global function set_default_executor, e.g. minescript.set_default_executor(minescript.render_loop). Default value is render_loop.

Setting an executor for a script function affects only the calls of that function within that script job. Concurrently running script jobs can set different executors for the same script function.

Script tasks

A task list allows a sequence of script functions to be called efficiently on a Java executor by batching script function calls to avoid successive roundtrips between Python and Java. A task is created by calling .as_task(...) on a script function, e.g. minescript.echo.as_task("Hello!").

Creating a task does not actually call the script function, but instead creates a description of a script function to be called, possibly with specific args, at some later point.

A task list is created by adding tasks to a Python list. Return values from tasks earlier in the list (which are not actual return values from script functions, but descriptions of return values of future invocations) can be passed as args to tasks later in the list, e.g:

import minescript

tasks = []
def add_task(task):
  tasks.append(task)
  return task

player = add_task(minescript.player.as_task())
player_name = add_task(minescript.Task.get_attr(player, "name"))
add_task(minescript.echo.as_task("Player name is:"))
add_task(minescript.echo.as_task(player_name))

# Runs the task list in a single cycle of the default executor (by default this is the render loop):
minescript.run_tasks(tasks)

# Runs the task list on the tick loop:
with minescript.tick_loop:
  minescript.run_tasks(tasks)

Tasks can be run immediately with run_tasks or scheduled to run repeatedly on every cycle of an executor with schedule_tick_tasks or schedule_render_tasks. Scheduled tasks can be cancelled with cancel_scheduled_tasks. (There is no script function for scheduling tasks on the script_loop. While the same effect can be achieved by calling run_tasks in a tight while loop within with script_loop: ... in your script, given the high frequency of the script_loop executor which can run thousands of times per second, you probably don’t want to do this.)

See Task for documentation of task-related script functions.

Async script functions

Async script functions allow scripts to run functions in the background and wait on them to complete. This is useful for script functions that can take a long time to complete, e.g. several seconds.

In this example, await_loaded_region is used to block script execution until a range of chunks has finished loading. This example uses a directly called script function that executes synchronously (i.e. it doesn’t return until the operation is complete):

import minescript

x, y, z = [int(p) for p in minescript.player().position]

# Waits until all chunks from (x ± 50, z ± 50) are loaded:
minescript.await_loaded_region(x - 50, z - 50, x + 50, z + 50)

minescript.echo("Chunks around player finished loading.")

This is an alternate version of the previous example, modified to use an async script function by calling .as_async(...) instead of a direct call of the script function:

import minescript

x, y, z = [int(p) for p in minescript.player().position]

# .as_async(...) causes the script function to return a "future" value:
future = minescript.await_loaded_region.as_async(x - 50, z - 50, x + 50, z + 50)

# Do other work while the chunks are loading in the background...
minescript.echo("Waiting for chunks around player to finish loading...")

# Wait for future to complete, i.e. wait for chunks to finish loading:
future.wait()
minescript.echo("Chunks around player finished loading.")

A future value returned from an async script function can be waited on with a timeout which raises TimeoutError if the timeout expires before the operation is able to complete. In this example, the message "Still waiting for chunks around player to finish loading..." is repeatedly echoed to the player’s chat every 10 seconds until the chunks in the given range have finished loading:

import minescript

x, y, z = [int(p) for p in minescript.player().position]
while True:
  try:
    # Wait with a 10-second timeout:
    minescript.await_loaded_region.as_async(x - 50, z - 50, x + 50, z + 50).wait(timeout=10)
    minescript.echo("Chunks around player finished loading.")
    break
  except TimeoutError:
    minescript.echo("Still waiting for chunks around player to finish loading...")

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.

BlockPos

Tuple representing (x: int, y: int, z: int) position in block space.

Vector3f

Tuple representing (x: float, y: float, z: float) position or offset in 3D space.

execute

Usage: execute(command: str)

Executes the given command.

If command is prefixed by a backslash, it’s treated as Minescript command, otherwise it’s treated as a Minecraft command (the slash prefix is optional).

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(*messages)

Echoes plain-text messages to the chat.

Echoed messages are visible only to the local player.

If multiple args are given, join messages with a space separating them.

Update in v4.0: Support multiple plain-text messages.

Since: v2.0

echo_json

Usage: echo_json(json_text)

Echoes JSON-formatted text to the chat.

Echoed text is visible only to the local player.

json_text may be a string representing JSON text, or a list or dict. If it’s a list or dict, convert it to a JSON string using the standard json module.

Since: v4.0

chat

Usage: chat(*messages)

Sends messages to the chat.

If messages[0] is a str starting with a slash or backslash, automatically prepends a space so that the messages are sent as a chat and not executed as a command. If len(messages) is greater than 1, join messages with a space separating them. Ignores empty messages.

Update in v4.0: Support multiple messages.

Since: v2.0

log

Usage: log(*messages)

Sends messages to latest.log.

Update in v4.0: Support multiple messages of any type. Auto-convert messages to str.

Since: v3.0

screenshot

Usage: screenshot(filename=None)

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.

Since: v2.1

job_info

Usage: job_info() -> List[JobInfo]

Return info about active Minescript jobs.

Returns:

• JobInfo. For the enclosing job, JobInfo.self is True.

Since: v4.0

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() -> List[float]

Gets the local player’s position.

Returns:

• player’s position as [x: float, y: float, z: float]

Update in v4.0: Removed done_callback arg. Use async_player_position() for async execution.

player_hand_items

Usage: player_hand_items() -> HandItems

Gets the items in the local player’s hands.

Returns:

• Items in player’s hands. (Legacy-style return value can be restored with options.legacy_dict_return_values = True)

Update in v4.0: Return HandItems instead of List[Dict[str, Any]] by default. Removed done_callback arg. Use async_player_hand_items() for async execution.

Since: v2.0

player_inventory

Usage: player_inventory() -> List[ItemStack]

Gets the items in the local player’s inventory.

Returns:

• Items in player’s inventory. (Legacy-style return value can be restored with options.legacy_dict_return_values = True)

Update in v4.0: Return List[ItemStack] instead of List[Dict[str, Any]] by default. Removed done_callback arg. Use async_player_inventory() for async execution.

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) -> int

Swaps an inventory item into the hotbar.

Args:

• slot: inventory slot (9 or higher) to swap into the hotbar

Returns:

• hotbar slot (0-8) into which the inventory item was swapped

Update in v4.0: Removed done_callback arg. Use `async_player_inventory_slot_to_hotbar(…) for async execution.

Since: v3.0

player_inventory_select_slot

Usage: player_inventory_select_slot(slot: int) -> int

Selects the given slot within the player’s hotbar.

Args:

• slot: hotbar slot (0-8) to select in the player’s hand

Returns:

• previously selected hotbar slot

Update in v4.0: Removed done_callback arg. Use async_player_inventory_select_slot(...) for async execution.

Since: v3.0

press_key_bind

Usage: press_key_bind(key_mapping_name: str, pressed: bool)

Presses/unpresses a mapped key binding.

Valid values of key_mapping_name include: “key.advancements”, “key.attack”, “key.back”, “key.chat”, “key.command”, “key.drop”, “key.forward”, “key.fullscreen”, “key.hotbar.1”, “key.hotbar.2”, “key.hotbar.3”, “key.hotbar.4”, “key.hotbar.5”, “key.hotbar.6”, “key.hotbar.7”, “key.hotbar.8”, “key.hotbar.9”, “key.inventory”, “key.jump”, “key.left”, “key.loadToolbarActivator”, “key.pickItem”, “key.playerlist”, “key.right”, “key.saveToolbarActivator”, “key.screenshot”, “key.smoothCamera”, “key.sneak”, “key.socialInteractions”, “key.spectatorOutlines”, “key.sprint”, “key.swapOffhand”, “key.togglePerspective”, “key.use”

Args:

• key_mapping_name: name of key binding
• pressed: if True, press the bound key, otherwise unpress it

Since: v4.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: if True, 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: if True, 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: if True, 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: if True, 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: if True, 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: if True, 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: if True, 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: if True, 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: if True, 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: if True, 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: if True, 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: if True, 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 axis
• pitch: 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:

• TargetedBlock for the block targeted by the player, or None if no block is targeted.

Update in v4.0: Return value changed from list to TargetedBlock.

Since: v3.0

player_get_targeted_entity

Usage: player_get_targeted_entity(max_distance: float = 20, nbt: bool = False) -> EntityData

Gets the entity targeted in the local player’s crosshairs, if any.

Args:

• max_distance: maximum distance to check for targeted entities
• nbt: if True, populate an "nbt" attribute for the player

Returns:

• EntityData for the entity targeted by the player, or None if no entity is targeted. (Legacy-style returned dict can be restored with options.legacy_dict_return_values = True)

Since: v4.0

player_health

Usage: player_health() -> float

Gets the local player’s health.

Since: v3.1

player

Usage: player(*, nbt: bool = False)

Gets attributes for the local player.

Args:

• nbt: if True, populate the nbt field for the player

Returns:

• EntityData representing a snapshot of values for the local player. (Legacy-style returned dict can be restored with options.legacy_dict_return_values = True)

Since: v4.0

players

Usage: players(*, nbt: bool = False, uuid: str = None, name: str = None, position: Vector3f = None, offset: Vector3f = None, min_distance: float = None, max_distance: float = None, sort: str = None, limit: int = None)

Gets a list of nearby players and their attributes.

Args:

• nbt: if True, populate an "nbt" attribute for each returned player
• uuid: regular expression for matching entities’ UUIDs (optional)
• name: regular expression for matching entities’ names (optional)
• position: position used with offset, min_distance, or max_distance to define a volume for filtering entities; default is the local player’s position (optional)
• offset: offset relative to position for selecting entities (optional)
• min_distance: min distance relative to position for selecting entities (optional)
• max_distance: max distance relative to position for selecting entities (optional)
• sort: one of “nearest”, “furthest”, “random”, or “arbitrary” (optional)
• limit: maximum number of entities to return (optional)

Returns:

• List[EntityData] representing a snapshot of values for the selected players. (Legacy returned dicts can be restored with options.legacy_dict_return_values = True)

Update in v4.0: Added args: uuid, name, type, position, offset, min_distance, max_distance, sort, limit. Return List[EntityData] instead of List[Dict[str, Any]] by default. Added uuid and id to returned players.

Update in v3.1: Added "health" and "local" attributes, and nbt arg to output "nbt" attribute.

Since: v2.1

entities

Usage: entities(*, nbt: bool = False, uuid: str = None, name: str = None, type: str = None, position: Vector3f = None, offset: Vector3f = None, min_distance: float = None, max_distance: float = None, sort: str = None, limit: int = None)

Gets a list of nearby entities and their attributes.

Args:

• nbt: if True, populate an "nbt" attribute for each returned entity (optional)
• uuid: regular expression for matching entities’ UUIDs (optional)
• name: regular expression for matching entities’ names (optional)
• type: regular expression for matching entities’ types (optional)
• position: position used with offset, min_distance, or max_distance to define a volume for filtering entities; default is the local player’s position (optional)
• offset: offset relative to position for selecting entities (optional)
• min_distance: min distance relative to position for selecting entities (optional)
• max_distance: max distance relative to position for selecting entities (optional)
• sort: one of “nearest”, “furthest”, “random”, or “arbitrary” (optional)
• limit: maximum number of entities to return (optional)

Returns:

• List[EntityData] representing a snapshot of values for the selected entities. (Legacy returned dicts can be restored with options.legacy_dict_return_values = True)

Update in v4.0: Added args: uuid, name, type, position, offset, min_distance, max_distance, sort, limit. Return List[EntityData] instead of List[Dict[str, Any]] by default. Added uuid, id, and passengers (only for entities with passengers) to returned entities.

Update in v3.1: Added "health" and "local" attributes, and nbt arg to output "nbt" attribute.

Since: v2.1

version_info

Usage: version_info() -> VersionInfo

Gets version info for Minecraft, Minescript, mod loader, launcher, and OS.

minecraft_class_name is the runtime class name of the main Minecraft class which may be obfuscated.

Returns:

• VersionInfo

Since: v4.0

world_info

Usage: world_info() -> WorldInfo

Gets world properties.

If the current world is a multiplayer world loaded from the server list, then the returned name and address attributes are the values as they appear in the server list; otherwise name is the name of the locally saved world and address is localhost.

day_ticks are the ticks associated with the day-night cycle.

Renamed from world_properties() from v3.1.

Returns:

• WorldInfo

Since: v4.0

getblock

Usage: getblock(x: int, y: int, z: int) -> str

Gets the type of block at position (x, y, z).

Args:

• x, y, z: position of block to get

Returns:

• block type at (x, y, z) as a string

getblocklist

Usage: getblocklist(positions: List[List[int]]) -> List[str]

Gets the types of block at the specified [x, y, z] positions.

Args:

list of positions as lists of x, y, z int coordinates, e.g. [[0, 0, 0], [0, 0, 1]]

Returns:

• block types at given positions as list of strings

Update in v4.0: Removed done_callback arg. Use async_getblocklist(...) for async execution.

Since: v2.1

await_loaded_region

Usage: await_loaded_region(x1: int, z1: int, x2: int, z2: int)

Waits for chunks to load in the region from (x1, z1) to (x2, z2).

Args:

• x1, z1, x2, z2: bounds of the region for awaiting loaded chunks
• timeout: if specified, timeout in seconds to wait for the region to load

Update in v4.0: Removed done_callback arg. Call now always blocks until region is loaded.

set_default_executor

Usage: set_default_executor(executor: minescript_runtime.FunctionExecutor)

Sets the default executor for script functions executed in the current script job.

Default value is minescript.render_loop.

Args:

• executor: one of minescript.tick_loop, minescript.render_loop, or minescript.script_loop

Since: v4.0

Task

Executable task that allows multiple operations to execute on the same executor cycle.

Task.as_list

Usage: @staticmethod Task.as_list(*values)

Creates a task that returns the given values as a list.

Task.get_index

Usage: @staticmethod Task.get_index(array, index)

Creates a task that looks up an array by index.

Task.get_attr

Usage: @staticmethod Task.get_attr(obj, attr)

Creates a task that looks up a map/dict by key.

Task.contains

Usage: @staticmethod Task.contains(container, element)

Creates a task that checks if a container (map, list, or string) contains an element.

Task.as_int

Usage: @staticmethod Task.as_int(*numbers)

Creates a task that converts a floating-point number to int.

Task.negate

Usage: @staticmethod Task.negate(condition)

Creates a task that negates a boolean value.

Task.is_null

Usage: @staticmethod Task.is_null(value)

Creates a task that checks a value against null or None.

Task.skip_if

Usage: @staticmethod Task.skip_if(condition)

Creates a task that skips the remainder of the task list if condition is true.

run_tasks

Usage: run_tasks(tasks: List[Task])

Runs tasks so that multiple tasks can be run on the same executor cycle.

schedule_tick_tasks

Usage: schedule_tick_tasks(tasks: List[Task]) -> int

Schedules a list of tasks to run every cycle of the tick loop.

Returns:

• ID of scheduled task list which can be passed to cancel_scheduled_tasks(task_list_id).

Since: v4.0

schedule_render_tasks

Usage: schedule_render_tasks(tasks: List[Task]) -> int

Schedules a list of tasks to run every cycle of the render loop.

Returns:

• ID of scheduled task list which can be passed to cancel_scheduled_tasks(task_list_id).

Since: v4.0

cancel_scheduled_tasks

Usage: cancel_scheduled_tasks(task_list_id: int)

Cancels a scheduled task list for the currently running job.

Args:

• task_list_id: ID of task list returned from schedule_tick_tasks() or schedule_render_tasks.

Returns:

• True if task_list_id was successfully cancelled, False otherwise.

Since: v4.0

KeyEvent

Key event data.

For a list of key codes, see: https://www.glfw.org/docs/3.4/group__keys.html action is 0 for key up, 1 for key down, and 2 for key repeat.

MouseEvent

Mouse event data.

action is 0 for mouse up and 1 for mouse down.

EventQueue

Queue for managing events.

Implements context management so that it can be used with a with expression to automatically unregister event listeners at the end of the block, e.g.

with EventQueue() as event_queue:
  event_queue.register_chat_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.CHAT and "knock knock" in event.message.lower():
      echo("Who's there?")

Since: v4.0

EventQueue.__init__

Usage: EventQueue()

Creates an event registration handler.

EventQueue.register_key_listener

Usage: EventQueue.register_key_listener()

Registers listener for EventType.KEY events as KeyEvent.

Example:

with EventQueue() as event_queue:
  event_queue.register_key_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.KEY:
      if event.action == 0:
        action = 'up'
      elif event.action == 1:
        action = 'down'
      else:
        action = 'repeat'
      echo(f"Got key {action} with code {event.key}")

EventQueue.register_mouse_listener

Usage: EventQueue.register_mouse_listener()

Registers listener for EventType.MOUSE events as MouseEvent.

Example:

with EventQueue() as event_queue:
  event_queue.register_mouse_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.MOUSE:
      echo(f"Got mouse {'up' if event.action == 0 else 'down'} of button {event.button}")

EventQueue.register_chat_listener

Usage: EventQueue.register_chat_listener()

Registers listener for EventType.CHAT events as ChatEvent.

Example:

with EventQueue() as event_queue:
  event_queue.register_chat_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.CHAT:
      if not event.message.startswith("> "):
        echo(f"> Got chat message: {event.message}")

EventQueue.register_outgoing_chat_interceptor

Usage: EventQueue.register_outgoing_chat_interceptor(*, prefix: str = None, pattern: str = None)

Registers listener for EventType.OUTGOING_CHAT_INTERCEPT events as ChatEvent.

Intercepts outgoing chat messages from the local player. Interception can be restricted to messages matching prefix or pattern. Intercepted messages can be chatted with chat().

prefix or pattern can be specified, but not both. If neither prefix nor pattern is specified, all outgoing chat messages are intercepted.

Args:

• prefix: if specified, intercept only the messages starting with this literal prefix
• pattern: if specified, intercept only the messages matching this regular expression

Example:

with EventQueue() as event_queue:
  event_queue.register_outgoing_chat_interceptor(pattern=".*%p.*")
  while True:
    event = event_queue.get()
    if event.type == EventType.OUTGOING_CHAT_INTERCEPT:
      # Replace "%p" in outgoing chats with your current position.
      chat(event.message.replace("%p", str(player().position)))

EventQueue.register_add_entity_listener

Usage: EventQueue.register_add_entity_listener()

Registers listener for EventType.ADD_ENTITY events as AddEntityEvent.

Example:

with EventQueue() as event_queue:
  event_queue.register_add_entity_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.ADD_ENTITY:
      echo(f"Entity added: {event.entity.name}")

EventQueue.register_block_update_listener

Usage: EventQueue.register_block_update_listener()

Registers listener for EventType.BLOCK_UPDATE events as BlockUpdateEvent.

Example:

with EventQueue() as event_queue:
  event_queue.register_block_update_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.BLOCK_UPDATE:
      echo(f"Block updated at {event.position} to {event.new_state}")

EventQueue.register_take_item_listener

Usage: EventQueue.register_take_item_listener()

Registers listener for EventType.TAKE_ITEM events as TakeItemEvent.

Example:

with EventQueue() as event_queue:
  event_queue.register_take_item_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.TAKE_ITEM:
      echo(f"Item taken: {event.item.type}")

EventQueue.register_damage_listener

Usage: EventQueue.register_damage_listener()

Registers listener for EventType.DAMAGE events as DamageEvent.

Example:

with EventQueue() as event_queue:
  event_queue.register_damage_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.DAMAGE:
      echo(f"Damage from {event.source}")

EventQueue.register_explosion_listener

Usage: EventQueue.register_explosion_listener()

Registers listener for EventType.EXPLOSION events as ExplosionEvent.

Example:

with EventQueue() as event_queue:
  event_queue.register_explosion_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.EXPLOSION:
      echo(f"Explosion at {event.position}")

EventQueue.register_chunk_listener

Usage: EventQueue.register_chunk_listener()

Registers listener for EventType.CHUNK events as ChunkEvent.

Example:

with EventQueue() as event_queue:
  event_queue.register_chunk_listener()
  while True:
    event = event_queue.get()
    if event.type == EventType.CHUNK:
      x = event.x_min
      z = event.z_min
      echo(f"Chunk {'loaded' if event.loaded else 'unloaded'} at {x}, {z}")

EventQueue.get

Usage: EventQueue.get(block: bool = True, timeout: float = None) -> Any

Gets the next event in the queue.

Args:

• block: if True, block until an event fires
• timeout: timeout in seconds to wait for an event if block is True

Returns:

• subclass-dependent event

Raises:

queue.Empty if block is True and timeout expires, or block is False and queue is empty.

KeyEventListener

Usage: KeyEventListener()

Deprecated listener for keyboard events. Use EventQueue.register_key_listener instead.

Update in v4.0: Deprecated in favor of EventQueue.register_key_listener.

Since: v3.2

ChatEventListener

Usage: ChatEventListener()

Deprecated listener for chat message events.

Use EventQueue.register_chat_message_listener instead.

Update in v4.0: Deprecated in favor of EventQueue.register_chat_message_listener.

Since: v3.2

screen_name

Usage: screen_name() -> str

Gets the current GUI screen name, if there is one.

Returns:

• Name of current screen (str) or None if no GUI screen is being displayed.

Since: v3.2

show_chat_screen

Usage: show_chat_screen(show: bool, prompt: str = None) -> str

Shows or hides the chat screen.

Args:

• show: if True, show the chat screen; otherwise hide it
• prompt: if show is True, insert prompt into chat input box upon showing chat screen.

Returns:

• True if chat screen was successfully shown (show=True) or hidden (show=False)

Since: v4.0

append_chat_history

Usage: append_chat_history(message: str)

Appends message to chat history, available via up and down arrows in chat.

Since: v4.0

chat_input

Usage: chat_input()

Gets state of chat input text.

Returns:

• [text, position] where text is str and position is int cursor position within text

Since: v4.0

set_chat_input

Usage: set_chat_input(text: str = None, position: int = None, color: int = None)

Sets state of chat input text.

Args:

• text: if specified, replace chat input text
• position: if specified, move cursor to this position within the chat input box
• color: if specified, set input text color, formatted as 0xRRGGBB

Since: v4.0

container_get_items

Usage: container_get_items() -> List[ItemStack]

Gets all items in an open container (chest, furnace, etc. with slots).

Returns:

• List of items if a container’s contents are displayed; None otherwise.

Since: v4.0

player_look_at

Usage: player_look_at(x: float, y: float, z: float)

Rotates the camera to look at a position.

Args:

• x: x position
• y: y position
• z: z position

Since: v4.0

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 blocks
• rotation: rotation matrix to apply to block coordinates read from world
• offset: offset to apply to block coordiantes (applied after rotation)
• comments: key, value pairs to include in the new blockpack
• safety_limit: if True, fail if requested volume spans more than 1600 chunks

Returns:

• a new BlockPack containing blocks read from the world

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: if True, relative filename is taken to be relative to Minecraft dir

Returns:

• a new BlockPack containing blocks read from the file

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

BlockPack.block_bounds

Usage: BlockPack.block_bounds() -> (BlockPos, BlockPos)

Returns min and max bounding coordinates of blocks in this BlockPack.

BlockPack.comments

Usage: BlockPack.comments() -> Dict[str, str]

Returns comments stored in this BlockPack.

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 world
• offset: offset to apply to block coordiantes (applied after rotation)

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: if True, relative filename is taken to be relative to Minecraft dir

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

BlockPack.__del__

Usage: del blockpack

Frees this BlockPack to be garbage collected.

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 set
• block_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 fill
• block_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 blocks
• rotation: rotation matrix to apply to block coordinates before adding to blockpacker
• offset: offset to apply to block coordiantes (applied after rotation)

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

BlockPacker.__del__

Usage: del blockpacker

Frees this BlockPacker to be garbage collected.

java_class

Usage: java_class(name: str) -> JavaHandle

Looks up Java class by fully qualified name. Returns handle to the Java class object.

Example: java_class("net.minescript.common.Minescript")

If running Minecraft with unobfuscated Java symbols: java_class("net.minecraft.client.Minecraft")

If running Minecraft with obfuscated symbols, name must be the fully qualified and obfuscated class name.

Since: v4.0

java_string

Usage: java_string(s: str) -> JavaHandle

Returns handle to a Java String. Since: v4.0

java_double

Usage: java_double(d: float) -> JavaHandle

Returns handle to a Java Double. Since: v4.0

java_float

Usage: java_float(f: float) -> JavaHandle

Returns handle to a Java Float. Since: v4.0

java_long

Usage: java_long(l: int) -> JavaHandle

Returns handle to a Java Long. Since: v4.0

java_int

Usage: java_int(i: int) -> JavaHandle

Returns handle to a Java Integer Since: v4.0

java_bool

Usage: java_bool(b: bool) -> JavaHandle

Returns handle to a Java Boolean. Since: v4.0

java_ctor

Usage: java_ctor(clss: JavaHandle)

Returns handle to a constructor set for the given class handle.

Args:

• clss: Java class handle returned from java_class

Since: v4.0

java_new_instance

Usage: java_new_instance(ctor: JavaHandle, *args: List[JavaHandle]) -> JavaHandle

Creates new Java instance.

Args:

• ctor: constructor set returned from java_ctor
• args: handles to Java objects to pass as constructor params

Returns:

• handle to newly created Java object.

Since: v4.0

java_member

Usage: java_member(clss: JavaHandle, name: str) -> JavaHandle

Gets Java member(s) matching name.

Returns:

• Java member object for use with java_access_field or java_call_method.

Since: v4.0

java_access_field

Usage: java_access_field(target: JavaHandle, field: JavaHandle) -> JavaHandle

Accesses a field on a target Java object.

Args:

• target: Java object handle from which to access a field
• field: handle returned from java_member

Returns:

• Handle to Java object returned from field access, or None if null.

Since: v4.0

java_call_method

Usage: java_call_method(target: JavaHandle, method: JavaHandle, *args: List[JavaHandle]) -> JavaHandle

Invokes a method on a target Java object.

Args:

• target: Java object handle on which to call a method
• method: handle returned from java_member
• args: handles to Java objects to pass as method params

Returns:

• handle to Java object returned from method call, or None if null.

Since: v4.0

java_call_script_function

Usage: java_call_script_function(func_name: Union[str, JavaHandle], *args: List[JavaHandle]) -> JavaHandle

Calls the requested script function with Java params.

Args:

• func_name: name of the script function, as a Python str or a handle to a Java String
• args: handles to Java objects to pass as args to the script function

Returns:

• handle to Java object (Optional<JsonElement>) returned from the script function.

Since: v4.0

java_array_length

Usage: java_array_length(array: JavaHandle) -> int

Returns length of Java array as Python integer. Since: v4.0

java_array_index

Usage: java_array_index(array: JavaHandle, i: int) -> JavaHandle

Gets indexed element of Java array handle.

Args:

• array: handle to Java array object
• i: index into array

Returns:

• handle to object at array[i] in Java, or None if null.

Since: v4.0

java_to_string

Usage: java_to_string(target: JavaHandle) -> str

Returns Python string from calling target.toString() in Java. Since: v4.0

java_assign

Usage: java_assign(dest: JavaHandle, source: JavaHandle)

Reassigns dest to reference the object referenced by source.

Upon success, both dest and source reference the same Java object that was initially referenced by source.

Since: v4.0

java_release

Usage: java_release(*targets: List[JavaHandle])

Releases Java reference(s) referred to by targets. Since: v4.0