# Table of Contents - [Documentation – Minescript](#documentation-minescript) - [Documentation (v2.1) – Minescript](#documentation-v2-1-minescript) - [Documentation (v1.19) – Minescript](#documentation-v1-19-minescript) - [Documentation (v2.0) – Minescript](#documentation-v2-0-minescript) - [Documentation (3.0) – Minescript](#documentation-3-0-minescript) --- # Documentation – Minescript [Skip to content](https://minescript.net/docs#content) Minescript v5.0 docs -------------------- _View docs for all versions of Minescript on [GitHub](https://github.com/maxuser0/minescript/blob/main/docs/README.md) ._ Table of contents: * [In-game commands](https://minescript.net/docs#in-game-commands) * [Command basics](https://minescript.net/docs#command-basics) * [Built-in commands](https://minescript.net/docs#built-in-commands) * [Configuration](https://minescript.net/docs#configuration) * [Pyjinn](https://minescript.net/docs#pyjinn) * [Python API](https://minescript.net/docs#python-api) * [Script input](https://minescript.net/docs#script-input) * [Script output](https://minescript.net/docs#script-output) * [Script functions](https://minescript.net/docs#script-functions) * [Async script functions](https://minescript.net/docs#async-script-functions) * [java module](https://minescript.net/docs#java-module) * [minescript module](https://minescript.net/docs#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](https://minescript.net/docs#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`](https://minescript.net/docs#minescript-module) 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](https://minescript.net/docs#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](https://minescript.net/docs#copy) . #### jobs _Usage:_ `\jobs [all]` Lists the currently running Minescript jobs. `\jobs` with no arguments list all jobs that are not managed by a parent job. `\jobs all` lists all jobs, including child jobs, e.g. Pyjinn scripts embedded within a parent Python job. See: [Pyjinn: Embedding Pyjinn in Python scripts](https://minescript.net/pyjinn#embedding-pyjinn-in-python-scripts) #### 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](https://minescript.net/docs#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](https://minescript.net/docs#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](https://www.glfw.org/docs/3.3/group__keys.html) 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. Pyjinn ------ **Pyjinn** is Minescript’s integrated interpreter that’s based on Python syntax. See [Pyjinn docs](https://minescript.net/pyjinn) for details. Python API ---------- ### Script input Parameters can be passed from Minecraft as input to a Python script as `sys.argv`. For example, this Python script prints the result of rolling dice to the chat, visible only to the local user (copy code to `minecraft/minescript/roll_dice.py`): import random import sys def print_dice_roll(num_dice: int, num_sides: int): results = [] for _ in range(num_dice): results.append(random.randint(1, num_sides)) die_or_dice = "die" if num_dice == 1 else "dice" print(f"Rolled {num_dice} {num_sides}-sided {die_or_dice}: {results}") # Read arguments from `sys.argv` list. # First arg for the number of dice is required. # Second arg for the number of sides on the dice is optional, # defaulting to 6. num_dice = int(sys.argv[1]) num_sides = int(sys.argv[2]) if len(sys.argv) > 2 else 6 print_dice_roll(num_dice, num_sides) The above script can be run from the Minecraft in-game chat to output the result of rolling two 6-sided dice: \roll_dice 2 6 That command passes arguments that set `num_dice` to `2` and `num_sides` to `6`. ### Script output Minescript Python scripts can process outputs using `sys.stdout` and `sys.stderr` (e.g. using Python’s built-in `print` function), or using functions defined in `minescript.py`: [`echo`](https://minescript.net/docs#echo) , [`echo_json`](https://minescript.net/docs#echo_json) , [`chat`](https://minescript.net/docs#chat) , and [`log`](https://minescript.net/docs#log) . # Prints a plain-text message to the in-game chat that's # visible only to you (displayed as white text): print("Note to self...") # Same as the previous print(...) statement, except # that the output to stdout is explicit: print("Note to self...", file=sys.stdout) # Same output as the previous print(...) statements, # but using a Minescript function (behavior can be # different from above print(...) statements when # using "Script output redirection"; see below): import minescript minescript.echo("Note to self...") # Echo JSON-formatted text (for styled and colored text) # as a JSON string to the in-game chat only to yourself: minescript.echo_json('{"text":"hello!", "color":"green"}') # Or as a Python dict or list converted to JSON: minescript.echo_json({"text":"hello!", "color":"green"}) # Prints a plain-text message to the in-game chat that's # visible only to you, displayed as yellow text so that # it's visually distinguishable from text written to stdout: print("Note to self...", file=sys.stderr) # Send a chat message that's visible to all players # in the world: minescript.chat("hi, friends!") # Log a message to Minecrafts log file # (in minecraft/logs/latest.log): minescript.log("This is a debug message that does not appear in-game.") #### Script output redirection By default, output to a script’s stdout (typically as `print("...")`) and stderr (e.g. `print("...", file=sys.stderr)`) appears as plain white (stdout) or yellow (stderr) text, visible only to you. But this behavior can be overridden for a script job by using redirection operators at the end of the Minescript command that’s entered into the chat. Here’s an example script which can be copied to `minecraft/minescript/output_example.py`: import sys print("Output to stdout") print("Output to stderr", file=sys.stderr) The script can be run from the in-game chat as: \output_example The text `Output to stdout` should appear in white in the chat, and the text `Output to stderr` should appear in yellow, both visible only to you. But if you add `> chat` to the command like this: \output_example > chat then the output to stdout is redirected to the multiple-player chat. Similarly, output can be redirected to the Minecraft log file (`minecraft/logs/latest.log`) so that it doesn’t appear in the in-game chat, not even for you: \output_example > log Output to stdout can be disabled entirely for a script job by redirecting with `> null`: \output_example > null Output to stderr can similarly be redirected with `2>`: \output_example 2> chat \output_example 2> log \output_example 2> null Both stdout and stderr can be redirected separately for the same script job, e.g. redirect stdout to the multiple-player chat and stderr to the Minecraft log file without displaying it in the chat, not even to yourself: \output_example > chat 2> log The space after `>` is optional: \output_example >chat 2>log ### Script functions Script functions imported from [`minescript.py`](https://minescript.net/docs#minescript-module) can be called as functions or [asynchronously](https://minescript.net/docs#async-script-functions) . 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`](https://minescript.net/docs#execute) , [`echo`](https://minescript.net/docs#echo) , [`echo_json`](https://minescript.net/docs#echo_json) , [`chat`](https://minescript.net/docs#chat) , and [`log`](https://minescript.net/docs#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`](https://minescript.net/docs#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. _**Note:** Script tasks using `.as_task()`, `run_tasks()`, `schedule_tick_tasks()`, and `schedule_render_tasks()` have been removed in Minescript 5.0 because their functionality is redundant with and less expressive than embedded Pyjinn scripts. For embedding Pyjinn scripts within Python scripts see: [Pyjinn: Embedding Pyjinn in Python scripts](https://minescript.net/pyjinn#embedding-pyjinn-in-python-scripts) _ ### 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`](https://minescript.net/docs#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...") ### java module Library for using Java reflection from Python, wrapping the low-level Java API script functions (`java_*`). _Example:_ from minescript import echo from java import JavaClass Minecraft = JavaClass("net.minecraft.client.Minecraft") minecraft = Minecraft.getInstance() echo("fps:", minecraft.getFps()) * [`AutoReleasePool`](https://minescript.net/docs#autoreleasepool) * [`callAsyncScriptFunction`](https://minescript.net/docs#callasyncscriptfunction) * [`callScriptFunction`](https://minescript.net/docs#callscriptfunction) * [`eval_pyjinn_script`](https://minescript.net/docs#eval_pyjinn_script) * [`Float`](https://minescript.net/docs#float) * [`import_pyjinn_script`](https://minescript.net/docs#import_pyjinn_script) * [`JavaBoundMember`](https://minescript.net/docs#javaboundmember) * [`JavaClassType`](https://minescript.net/docs#javaclasstype) * [`JavaFloat`](https://minescript.net/docs#javafloat) * [`JavaFuture`](https://minescript.net/docs#javafuture) * [`JavaInt`](https://minescript.net/docs#javaint) * [`JavaObject`](https://minescript.net/docs#javaobject) * [`JavaRef`](https://minescript.net/docs#javaref) * [`JavaString`](https://minescript.net/docs#javastring) #### AutoReleasePool Context manager for managing Java references in Python using `with` blocks. _Example:_ import minescript from java import * with AutoReleasePool() as auto: Object_class = auto(java_class("java.lang.Object")) Object_hashCode = auto(java_member(Object_class, "hashCode")) hello_string = auto(java_string("hello")) hash_value = auto(java_call_method(hello_string, Object_hashCode)) minescript.echo(java_to_string(hash_value)) All the Java references captured with `auto()` in the example are released when the `with` block above exits, automatically calling [`java_release()`](https://minescript.net/docs#java_release) . #### AutoReleasePool.\_\_call\_\_ _Usage:_ `AutoReleasePool.__call__(ref: JavaHandle) -> JavaHandle` Track `ref` for auto-release when this pool is deleted or goes out of scope. _Returns:_ * `ref` for convenient wrapping of functions returning a JavaHandle. #### Float Wrapper class for mirroring Java `float` in Python. Python `float` maps to Java `double`, and Python doesn’t have a built-in single-precision float. value: float #### JavaRef Reference counter for Java objects referenced from Python. #### JavaObject Python representation of a Java object. #### JavaObject.\_\_init\_\_ _Usage:_ `JavaObject(target_id: JavaHandle, ref: [JavaRef](https://minescript.net/docs#javaref) = None, is_script: bool = False)` Constructs a Python handle to a Java object given a `JavaHandle`. #### JavaObject.toString _Usage:_ `JavaObject.toString() -> str` Returns a `str` representation of `this.toString()` from Java. #### JavaObject.set\_value _Usage:_ `JavaObject.set_value(value: Any)` Sets this JavaObject to reference `value` instead. `value` can be any of the following types: – bool: converted to Java Boolean – int: converted to Java Integer – Float: converted to Java Float – float: converted to Java Double – str: converted to Java String – JavaObject: this JavaObject will reference the same Java object as `value` #### JavaObject.\_\_getattr\_\_ _Usage:_ `JavaObject.__getattr__(name: str)` Accesses the field or method named `name`. _Args:_ * `name`: name of a field or method on this JavaObject’s class _Returns:_ * If `name` matches a field on this JavaObject’s class, then return the value of that field as a Python primitive or new JavaObject. Otherwise return a [`JavaBoundMember`](https://minescript.net/docs#javaboundmember) equivalent to the Java expression `this::methodName`. #### JavaObject.\_\_len\_\_ _Usage:_ `JavaObject.__len__() -> int` If this JavaObject represents a Java array, returns the length of the array. Raises `TypeError` if this isn’t an array. #### JavaObject.\_\_bool\_\_ _Usage:_ `JavaObject.__bool__() -> int` Returns False if the Java reference is null. #### JavaObject.\_\_getitem\_\_ _Usage:_ `JavaObject.__getitem__(i: int)` If this JavaObject represents a Java array, returns `array[i]`. _Args:_ * `i`: index into array from which to get an element _Returns:_ * `array[i]` as a Python primitive value or JavaObject. _Raises:_ `TypeError` if this isn’t an array. #### JavaBoundMember Representation of a Java method reference in Python. #### JavaBoundMember.\_\_init\_\_ _Usage:_ `JavaBoundMember(target_class_id: JavaHandle, target, name: str, ref: [JavaRef](https://minescript.net/docs#javaref) = None, script: [JavaObject](https://minescript.net/docs#javaobject) = None)` Member that’s bound to a target object, representing a field or method. _Args:_ * `target_class_id`: Java object ID of enclosing class for this member * `target`: either Java object ID of the target through which this member is accessed * `name`: name of this member * `ref`: JavaRef to manage reference lifetime (optional) * `script`: Pyjinn Script object for accessing and calling script functions (optional) #### JavaBoundMember.\_\_call\_\_ _Usage:_ `JavaBoundMember.__call__(*args)` Calls the bound method with the given `args`. _Returns:_ * A Python primitive (bool, int, float, str) if applicable, otherwise a JavaObject. #### JavaInt JavaObject subclass for Java Integer. #### JavaFloat JavaObject subclass for Java Float. #### JavaString JavaObject subclass for Java String. #### JavaClassType JavaObject subclass for Java class objects. #### JavaClassType.is\_enum _Usage:_ `JavaClassType.is_enum()` Returns `True` if this class represents a Java enum type. #### JavaClassType.\_\_getattr\_\_ _Usage:_ `JavaClassType.__getattr__(name)` Accesses the static field or static method named `name` on this Java class. _Args:_ * `name`: name of a static field or static method on this Java class. _Returns:_ * If `name` matches a static field on this Java class, then return the value of that field as a new JavaObject. Otherwise return a [`JavaBoundMember`](https://minescript.net/docs#javaboundmember) equivalent to the Java expression `ThisClass::staticMethodName`. #### JavaClassType.\_\_call\_\_ _Usage:_ `JavaClassType.__call__(*args)` Calls the constructor for this Java class that takes the given `args`, if applicable. _Returns:_ * JavaObject representing the newly constructed Java object. #### callScriptFunction _Usage:_ `callScriptFunction(func_name: str, *args) -> [JavaObject](https://minescript.net/docs#javaobject) ` Calls the given Minescript script function. _Args:_ * `func_name`: name of a Minescript script function * `args`: args to pass to the given script function _Returns:_ * The return value of the given script function as a Python primitive type or JavaObject. #### JavaFuture Java value that will become available in the future when an async function completes. #### JavaFuture.wait _Usage:_ `JavaFuture.wait(timeout=None)` Waits for the async function to complete. _Args:_ * `timeout`: if not `None`, timeout in seconds to wait on the async function to complete _Returns:_ * Python primitive value or JavaObject returned from the async function upon completion. #### callAsyncScriptFunction _Usage:_ `callAsyncScriptFunction(func_name: str, *args) -> [JavaFuture](https://minescript.net/docs#javafuture) ` Calls the given Minescript script function asynchronously. _Args:_ * `func_name`: name of a Minescript script function * `args`: args to pass to the given script function _Returns:_ * [`JavaFuture`](https://minescript.net/docs#javafuture) that will hold the return value of the async funcion when complete. #### eval\_pyjinn\_script _Usage:_ `eval_pyjinn_script(script_code: str) -> [JavaObject](https://minescript.net/docs#javaobject) ` Creates a Pyjinn script given source code as a string. See: [Embedding Pyjinn in Python scripts](https://minescript.net/pyjinn#embedding-pyjinn-in-python-scripts) _Args:_ * `script_code`: Pyjinn source code _Returns:_ * new Java object of type `org.pyjinn.interpreter.Script` Since: v5.0 #### import\_pyjinn\_script _Usage:_ `import_pyjinn_script(pyj_filename: str)` Imports a Pyjinn script from a `.pyj` file. See: [Embedding Pyjinn in Python scripts](https://minescript.net/pyjinn#embedding-pyjinn-in-python-scripts) _Args:_ * `pyj_filename`: name a of `.pyj` file containing Pyjinn code to import _Returns:_ * new Java object of type `org.pyjinn.interpreter.Script` Since: v5.0 ### minescript module _Usage:_ `import minescript # from Python script` This module contains APIs for scripts to call into the Minescript mod. It should be imported by scripts as a library and not run directly. APIs in this module are compatible with both Python and Pyjinn scripts unless `"Compatibility:"` is specified. * [`add_event_listener`](https://minescript.net/docs#add_event_listener) * [`AddEntityEvent`](https://minescript.net/docs#addentityevent) * [`append_chat_history`](https://minescript.net/docs#append_chat_history) * [`await_loaded_region`](https://minescript.net/docs#await_loaded_region) * [`BlockPack`](https://minescript.net/docs#blockpack) * [`BlockPacker`](https://minescript.net/docs#blockpacker) * [`BlockPackerException`](https://minescript.net/docs#blockpackerexception) * [`BlockPos`](https://minescript.net/docs#blockpos) * [`BlockRegion`](https://minescript.net/docs#blockregion) * [`BlockUpdateEvent`](https://minescript.net/docs#blockupdateevent) * [`chat`](https://minescript.net/docs#chat) * [`chat_input`](https://minescript.net/docs#chat_input) * [`ChatEvent`](https://minescript.net/docs#chatevent) * [`ChatEventListener`](https://minescript.net/docs#chateventlistener) * [`ChunkEvent`](https://minescript.net/docs#chunkevent) * [`combine_rotations`](https://minescript.net/docs#combine_rotations) * [`container_get_items`](https://minescript.net/docs#container_get_items) * [`DamageEvent`](https://minescript.net/docs#damageevent) * [`echo`](https://minescript.net/docs#echo) * [`echo_json`](https://minescript.net/docs#echo_json) * [`entities`](https://minescript.net/docs#entities) * [`EntityData`](https://minescript.net/docs#entitydata) * [`EventQueue`](https://minescript.net/docs#eventqueue) * [`execute`](https://minescript.net/docs#execute) * [`ExplosionEvent`](https://minescript.net/docs#explosionevent) * [`flush`](https://minescript.net/docs#flush) * [`get_block`](https://minescript.net/docs#get_block) * [`get_block_list`](https://minescript.net/docs#get_block_list) * [`get_block_region`](https://minescript.net/docs#get_block_region) * [`getblock`](https://minescript.net/docs#getblock) * [`getblocklist`](https://minescript.net/docs#getblocklist) * [`HandItems`](https://minescript.net/docs#handitems) * [`ItemStack`](https://minescript.net/docs#itemstack) * [`java_access_field`](https://minescript.net/docs#java_access_field) * [`java_array_index`](https://minescript.net/docs#java_array_index) * [`java_array_length`](https://minescript.net/docs#java_array_length) * [`java_assign`](https://minescript.net/docs#java_assign) * [`java_bool`](https://minescript.net/docs#java_bool) * [`java_call_method`](https://minescript.net/docs#java_call_method) * [`java_call_script_function`](https://minescript.net/docs#java_call_script_function) * [`java_class`](https://minescript.net/docs#java_class) * [`java_ctor`](https://minescript.net/docs#java_ctor) * [`java_double`](https://minescript.net/docs#java_double) * [`java_field_names`](https://minescript.net/docs#java_field_names) * [`java_float`](https://minescript.net/docs#java_float) * [`java_int`](https://minescript.net/docs#java_int) * [`java_long`](https://minescript.net/docs#java_long) * [`java_member`](https://minescript.net/docs#java_member) * [`java_method_names`](https://minescript.net/docs#java_method_names) * [`java_new_array`](https://minescript.net/docs#java_new_array) * [`java_new_instance`](https://minescript.net/docs#java_new_instance) * [`java_release`](https://minescript.net/docs#java_release) * [`java_string`](https://minescript.net/docs#java_string) * [`java_to_string`](https://minescript.net/docs#java_to_string) * [`job_info`](https://minescript.net/docs#job_info) * [`JobInfo`](https://minescript.net/docs#jobinfo) * [`KeyEvent`](https://minescript.net/docs#keyevent) * [`KeyEventListener`](https://minescript.net/docs#keyeventlistener) * [`log`](https://minescript.net/docs#log) * [`ManagedCallback`](https://minescript.net/docs#managedcallback) * [`MinescriptRuntimeOptions`](https://minescript.net/docs#minescriptruntimeoptions) * [`MouseEvent`](https://minescript.net/docs#mouseevent) * [`player`](https://minescript.net/docs#player) * [`player_get_targeted_block`](https://minescript.net/docs#player_get_targeted_block) * [`player_get_targeted_entity`](https://minescript.net/docs#player_get_targeted_entity) * [`player_hand_items`](https://minescript.net/docs#player_hand_items) * [`player_health`](https://minescript.net/docs#player_health) * [`player_inventory`](https://minescript.net/docs#player_inventory) * [`player_inventory_select_slot`](https://minescript.net/docs#player_inventory_select_slot) * [`player_inventory_slot_to_hotbar`](https://minescript.net/docs#player_inventory_slot_to_hotbar) * [`player_look_at`](https://minescript.net/docs#player_look_at) * [`player_name`](https://minescript.net/docs#player_name) * [`player_orientation`](https://minescript.net/docs#player_orientation) * [`player_position`](https://minescript.net/docs#player_position) * [`player_press_attack`](https://minescript.net/docs#player_press_attack) * [`player_press_backward`](https://minescript.net/docs#player_press_backward) * [`player_press_drop`](https://minescript.net/docs#player_press_drop) * [`player_press_forward`](https://minescript.net/docs#player_press_forward) * [`player_press_jump`](https://minescript.net/docs#player_press_jump) * [`player_press_left`](https://minescript.net/docs#player_press_left) * [`player_press_pick_item`](https://minescript.net/docs#player_press_pick_item) * [`player_press_right`](https://minescript.net/docs#player_press_right) * [`player_press_sneak`](https://minescript.net/docs#player_press_sneak) * [`player_press_sprint`](https://minescript.net/docs#player_press_sprint) * [`player_press_swap_hands`](https://minescript.net/docs#player_press_swap_hands) * [`player_press_use`](https://minescript.net/docs#player_press_use) * [`player_set_orientation`](https://minescript.net/docs#player_set_orientation) * [`players`](https://minescript.net/docs#players) * [`press_key_bind`](https://minescript.net/docs#press_key_bind) * [`remove_event_listener`](https://minescript.net/docs#remove_event_listener) * [`RenderEvent`](https://minescript.net/docs#renderevent) * [`Rotation`](https://minescript.net/docs#rotation) * [`Rotations`](https://minescript.net/docs#rotations) * [`screen_name`](https://minescript.net/docs#screen_name) * [`screenshot`](https://minescript.net/docs#screenshot) * [`set_chat_input`](https://minescript.net/docs#set_chat_input) * [`set_default_executor`](https://minescript.net/docs#set_default_executor) * [`set_interval`](https://minescript.net/docs#set_interval) * [`set_timeout`](https://minescript.net/docs#set_timeout) * [`show_chat_screen`](https://minescript.net/docs#show_chat_screen) * [`TakeItemEvent`](https://minescript.net/docs#takeitemevent) * [`TargetedBlock`](https://minescript.net/docs#targetedblock) * [`TickEvent`](https://minescript.net/docs#tickevent) * [`Vector3f`](https://minescript.net/docs#vector3f) * [`version_info`](https://minescript.net/docs#version_info) * [`VersionInfo`](https://minescript.net/docs#versioninfo) * [`world_info`](https://minescript.net/docs#world_info) * [`WorldEvent`](https://minescript.net/docs#worldevent) * [`WorldInfo`](https://minescript.net/docs#worldinfo) #### 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. #### MinescriptRuntimeOptions Minscript module options. Compatibility: Python only. legacy_dict_return_values: bool = False # set to `True` to emulate behavior before v4.0 #### 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: str=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 #### JobInfo job_id: int command: List[str] source: str status: str parent_job_id: Union[int, None] self: bool #### job\_info _Usage:_ `job_info() -> List[JobInfo]` Return info about active Minescript jobs. _Returns:_ * [`JobInfo`](https://minescript.net/docs#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. Compatibility: Python only. 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 [`player_position().as_async()`](https://minescript.net/docs#player_position) for async execution. #### ItemStack item: str count: int nbt: str = None slot: int = None selected: bool = None #### HandItems main_hand: ItemStack off_hand: ItemStack #### player\_hand\_items _Usage:_ `player_hand_items() -> [HandItems](https://minescript.net/docs#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`](https://minescript.net/docs#handitems) instead of `List[Dict[str, Any]]` by default. Removed `done_callback` arg. Use `player_hand_items.as_async()` 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 `player_inventory.as_async()` 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 mc1.21.4: No longer supported because ServerboundPickItemPacket was removed in Minecraft 1.21.4. Update in v4.0: Removed `done_callback` arg. Use `player_inventory_slot_to_hotbar.as_async(...)` 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 `player_inventory_select_slot.as_async(...)` 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() -> List[float]` 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) -> bool` 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 #### TargetedBlock position: BlockPos distance: float side: str type: str #### player\_get\_targeted\_block _Usage:_ `player_get_targeted_block(max_distance: float = 20) -> Union[TargetedBlock, None]` 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`](https://minescript.net/docs#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`](https://minescript.net/docs#targetedblock) . Since: v3.0 #### EntityData name: str type: str uuid: str id: int position: Vector3f yaw: float pitch: float velocity: Vector3f lerp_position: Vector3f = None health: float = None local: bool = None # `True` if this the local player passengers: List[str] = None # UUIDs of passengers as strings nbt: str = None #### player\_get\_targeted\_entity _Usage:_ `player_get_targeted_entity(max_distance: float = 20, nbt: bool = False) -> Union[EntityData, None]` 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`](https://minescript.net/docs#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) -> [EntityData](https://minescript.net/docs#entitydata) ` Gets attributes for the local player. _Args:_ * `nbt`: if `True`, populate the `nbt` field for the player _Returns:_ * [`EntityData`](https://minescript.net/docs#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](https://minescript.net/docs#vector3f) = None, offset: [Vector3f](https://minescript.net/docs#vector3f) = None, min_distance: float = None, max_distance: float = None, sort: str = None, limit: int = None) -> List[EntityData]` 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](https://minescript.net/docs#vector3f) = None, offset: [Vector3f](https://minescript.net/docs#vector3f) = None, min_distance: float = None, max_distance: float = None, sort: str = None, limit: int = None) -> List[EntityData]` 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 #### VersionInfo minecraft: str minescript: str mod_loader: str launcher: str os_name: str os_version: str minecraft_class_name: str pyjinn: str #### version\_info _Usage:_ `version_info() -> [VersionInfo](https://minescript.net/docs#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`](https://minescript.net/docs#versioninfo) Since: v4.0 #### WorldInfo game_ticks: int day_ticks: int raining: bool thundering: bool spawn: BlockPos hardcore: bool difficulty: str name: str address: str #### world\_info _Usage:_ `world_info() -> [WorldInfo](https://minescript.net/docs#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`](https://minescript.net/docs#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 Update in v5.0: Added alias [`get_block(...)`](https://minescript.net/docs#get_block) . #### get\_block Alias for [`getblock(...)`](https://minescript.net/docs#getblock) . Since: v5.0 #### 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 v5.0: Added alias [`get_block_list(...)`](https://minescript.net/docs#get_block_list) . Update in v4.0: Removed `done_callback` arg. Use `getblocklist.as_async(...)` for async execution. Since: v2.1 #### get\_block\_list Alias for [`getblocklist(...)`](https://minescript.net/docs#getblocklist) . Since: v5.0 #### BlockRegion Accessor for blocks within an axis-aligned bounding box. See [`get_block_region(...)`](https://minescript.net/docs#get_block_region) for creating a [`BlockRegion`](https://minescript.net/docs#blockregion) . Since: v5.0 #### BlockRegion.\_\_init\_\_ _Usage:_ `BlockRegion(min_pos: [BlockPos](https://minescript.net/docs#blockpos) , max_pos: [BlockPos](https://minescript.net/docs#blockpos) , blocks: Tuple[str, ...])` Creates a block region between `min_pos` and `max_pos`, inclusive. _Args:_ * `min_pos`: minimum position of axis-aligned bounding box * `max_pos`: maximum position of axis-aligned bounding box * `blocks`: tuple of block type strings covering the volume of blocks between `min_pos` and `max_pos`, inclusive; given Lx, Ly, Lz lengths of the bounding box in x, y, and z dimensions, the first value in the tuple represents the block at the min\_pos; the first Lx values represent the min y, z edge of the volume; the first Lx \* Lz values represent the blocks in the min y plane of the volume; the last value represents the block at max\_pos. #### BlockRegion.get\_block _Usage:_ `BlockRegion.get_block(x: int, y: int, z: int) -> str` Gets the type of block at position (x, y, z). #### BlockRegion.get\_index _Usage:_ `BlockRegion.get_index(x: int, y: int, z: int) -> int` Gets the index into `blocks` sequence for position (x, y, z). #### get\_block\_region _Usage:_ `get_block_region(pos1: [BlockPos](https://minescript.net/docs#blockpos) , pos2: [BlockPos](https://minescript.net/docs#blockpos) , safety_limit: bool = True) -> [BlockRegion](https://minescript.net/docs#blockregion) ` Gets the types of blocks in the axis-aligned bounding box between pos1 and pos2, inclusive. _Args:_ * `pos1, pos2`: opposing corners of an axis-aligned bounding box (aabb) * `safety_limit`: if `True`, fail if requested volume spans more than 1600 chunks _Returns:_ * [`BlockRegion`](https://minescript.net/docs#blockregion) covering the requested volume of blocks. Since: v5.0 #### 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 Compatibility: Python only. 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` Compatibility: Python only. 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. type: str time: float key: int scan_code: int action: int modifiers: int screen: str #### MouseEvent Mouse event data. `action` is 0 for mouse up and 1 for mouse down. type: str time: float button: int action: int modifiers: int x: float y: float screen: str = None #### ChatEvent type: str time: float message: str #### AddEntityEvent type: str time: float entity: EntityData #### BlockUpdateEvent type: str time: float position: BlockPos old_state: str new_state: str #### TakeItemEvent type: str time: float player_uuid: str item: EntityData amount: int #### DamageEvent type: str time: float entity_uuid: str cause_uuid: str source: str #### ExplosionEvent type: str time: float position: Vector3f blockpack_base64: str #### ChunkEvent type: str time: float loaded: bool x_min: int z_min: int x_max: int z_max: int #### WorldEvent type: str time: float connected: bool #### 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?") Compatibility: Python only. (See [`add_event_listener`](https://minescript.net/docs#add_event_listener) for Pyjinn event handling.) 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`](https://minescript.net/docs#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`](https://minescript.net/docs#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`](https://minescript.net/docs#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`](https://minescript.net/docs#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()`](https://minescript.net/docs#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`](https://minescript.net/docs#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`](https://minescript.net/docs#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`](https://minescript.net/docs#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`](https://minescript.net/docs#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`](https://minescript.net/docs#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`](https://minescript.net/docs#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.register\_world\_listener _Usage:_ `EventQueue.register_world_listener()` Registers listener for `EventType.WORLD` events as [`WorldEvent`](https://minescript.net/docs#worldevent) . Script jobs are automatically terminated when the user’s game client disconnects from a world unless the script has an active “world” listener registered. All script jobs, including ones with “world” listeners, are terminated when the game client exits. _Example:_ with EventQueue() as event_queue: event_queue.register_world_listener() while True: event = event_queue.get() if event.type == EventType.WORLD: if event.connected: log(f"Connected to world {world_info().name}.") else: log("Disconnected from world.") Since: v5.0 #### 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`](https://minescript.net/docs#eventqueueregister_key_listener) instead. Compatibility: Python only. Update in v4.0: Deprecated in favor of [`EventQueue.register_key_listener`](https://minescript.net/docs#eventqueueregister_key_listener) . Since: v3.2 #### ChatEventListener _Usage:_ `ChatEventListener()` Deprecated listener for chat message events. Use `EventQueue.register_chat_message_listener` instead. Compatibility: Python only. Update in v4.0: Deprecated in favor of `EventQueue.register_chat_message_listener`. Since: v3.2 #### screen\_name _Usage:_ `screen_name() -> Union[str, None]` 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) -> bool` 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() -> List[Union[str, int]]` 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`](https://minescript.net/docs#blockpack) and [`BlockPacker`](https://minescript.net/docs#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](https://minescript.net/docs#rotation) , rot2: [Rotation](https://minescript.net/docs#rotation) , /) -> [Rotation](https://minescript.net/docs#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`](https://minescript.net/docs#blockpacker) . Since: v3.0 #### BlockPack.read\_world _Usage:_ `@classmethod BlockPack.read_world(pos1: [BlockPos](https://minescript.net/docs#blockpos) , pos2: [BlockPos](https://minescript.net/docs#blockpos) , *, rotation: [Rotation](https://minescript.net/docs#rotation) = None, offset: [BlockPos](https://minescript.net/docs#blockpos) = None, comments: Dict[str, str] = {}, safety_limit: bool = True) -> [BlockPack](https://minescript.net/docs#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](https://minescript.net/docs#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](https://minescript.net/docs#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](https://minescript.net/docs#rotation) = None, offset: [BlockPos](https://minescript.net/docs#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.visit\_blocks _Usage:_ `BlockPack.visit_blocks(setblock: Callable[[int, int, int, str], None], fill: Callable[[int, int, int, int, int, int, str], None]) -> None` Invokes the given callbacks to visit all the blocks in this BlockPack. _Args:_ * `setblock`: for each block that’s not adjacent to any blocks of the same type, invoke this as setblock(x, y, z, block) * `fill`: for each axis-aligned bounding box (aabb) of blocks of the same type greater than 1x1x1 between opposing corners (x1, y1, z1) and (x2, y2, z2), invoke this as fill(x1, y1, z1, x2, y2, z2, block) Compatibility: Pyjinn only. #### BlockPack.\_\_del\_\_ _Usage:_ `del blockpack` Frees this BlockPack to be garbage collected. #### BlockPackerException Exception thrown from failed [`BlockPack`](https://minescript.net/docs#blockpack) operations. #### BlockPacker BlockPacker is a mutable collection of blocks. Blocks can be added to a blockpacker by calling [`setblock(...)`](https://minescript.net/docs#blockpackersetblock) , [`fill(...)`](https://minescript.net/docs#blockpackerfill) , and/or [`add_blockpack(...)`](https://minescript.net/docs#blockpackeradd_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`](https://minescript.net/docs#blockpack) . Since: v3.0 #### BlockPacker.\_\_init\_\_ _Usage:_ `BlockPacker()` Creates a new, empty blockpacker. #### BlockPacker.setblock _Usage:_ `BlockPacker.setblock(pos: [BlockPos](https://minescript.net/docs#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`](https://minescript.net/docs#blockpackerexception) if blockpacker operation fails #### BlockPacker.fill _Usage:_ `BlockPacker.fill(pos1: [BlockPos](https://minescript.net/docs#blockpos) , pos2: [BlockPos](https://minescript.net/docs#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`](https://minescript.net/docs#blockpackerexception) if blockpacker operation fails #### BlockPacker.add\_blockpack _Usage:_ `BlockPacker.add_blockpack(blockpack: [BlockPack](https://minescript.net/docs#blockpack) , *, rotation: [Rotation](https://minescript.net/docs#rotation) = None, offset: [BlockPos](https://minescript.net/docs#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](https://minescript.net/docs#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")`](https://minescript.net/docs#java_class) If running Minecraft with unobfuscated Java symbols: [`java_class("net.minecraft.client.Minecraft")`](https://minescript.net/docs#java_class) If running Minecraft with obfuscated symbols, `name` must be the fully qualified and obfuscated class name. Compatibility: Python only. Since: v4.0 #### java\_string _Usage:_ `java_string(s: str) -> JavaHandle` Returns handle to a Java String. Compatibility: Python only. Since: v4.0 #### java\_double _Usage:_ `java_double(d: float) -> JavaHandle` Returns handle to a Java Double. Compatibility: Python only. Since: v4.0 #### java\_float _Usage:_ `java_float(f: float) -> JavaHandle` Returns handle to a Java Float. Compatibility: Python only. Since: v4.0 #### java\_long _Usage:_ `java_long(l: int) -> JavaHandle` Returns handle to a Java Long. Compatibility: Python only. Since: v4.0 #### java\_int _Usage:_ `java_int(i: int) -> JavaHandle` Returns handle to a Java Integer Compatibility: Python only. Since: v4.0 #### java\_bool _Usage:_ `java_bool(b: bool) -> JavaHandle` Returns handle to a Java Boolean. Compatibility: Python only. Since: v4.0 #### java\_ctor _Usage:_ `java_ctor(clazz: JavaHandle)` Returns handle to a constructor set for the given class handle. _Args:_ * `clazz`: Java class handle returned from [`java_class`](https://minescript.net/docs#java_class) Compatibility: Python only. 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`](https://minescript.net/docs#java_ctor) * `args`: handles to Java objects to pass as constructor params _Returns:_ * handle to newly created Java object. Compatibility: Python only. Since: v4.0 #### java\_member _Usage:_ `java_member(clazz: JavaHandle, name: str) -> JavaHandle` Gets Java member(s) matching `name`. _Args:_ * `clazz`: Java class handle returned from [`java_class`](https://minescript.net/docs#java_class) to look up member within * `name`: name of member to look up within `clazz` _Returns:_ * Java member object for use with [`java_access_field`](https://minescript.net/docs#java_access_field) or [`java_call_method`](https://minescript.net/docs#java_call_method) . Compatibility: Python only. Since: v4.0 #### java\_access\_field _Usage:_ `java_access_field(target: JavaHandle, field: JavaHandle) -> Union[JavaHandle, None]` 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`](https://minescript.net/docs#java_member) _Returns:_ * Handle to Java object returned from field access, or `None` if `null`. Compatibility: Python only. Since: v4.0 #### java\_call\_method _Usage:_ `java_call_method(target: JavaHandle, method: JavaHandle, *args: List[JavaHandle]) -> Union[JavaHandle, None]` 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`](https://minescript.net/docs#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`. Compatibility: Python only. 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`) returned from the script function. Compatibility: Python only. Since: v4.0 #### java\_array\_length _Usage:_ `java_array_length(array: JavaHandle) -> int` Returns length of Java array as Python integer. Compatibility: Python only. Since: v4.0 #### java\_array\_index _Usage:_ `java_array_index(array: JavaHandle, i: int) -> Union[JavaHandle, None]` 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`. Compatibility: Python only. Since: v4.0 #### java\_new\_array _Usage:_ `java_new_array(element_type: JavaHandle, *elements: List[JavaHandle]) -> JavaHandle` Creates a new Java array of the given element type with the given elements. _Args:_ * `element_type`: handle to Java class (Class) to use for the new array’s type * `elements`: handles to Java objects to populate the new array _Returns:_ * handle to new Java array. Compatibility: Python only. Since: v5.0 #### java\_to\_string _Usage:_ `java_to_string(target: JavaHandle) -> str` Returns Python string from calling `target.toString()` in Java. Compatibility: Python only. 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`. Compatibility: Python only. Since: v4.0 #### java\_field\_names _Usage:_ `java_field_names(clazz: JavaHandle) -> List[str]` Returns a list of fields names for the class referenced by handle `clazz`. If mappings are installed, official field names are returned. Compatibility: Python only. Since: v5.0 #### java\_method\_names _Usage:_ `java_method_names(clazz: JavaHandle) -> List[str]` Returns a list of methods names for the class referenced by handle `clazz`. If mappings are installed, official method names are returned. Compatibility: Python only. Since: v5.0 #### java\_release _Usage:_ `java_release(*targets: List[JavaHandle])` Releases Java reference(s) referred to by `targets`. Compatibility: Python only. Since: v4.0 #### add\_event\_listener _Usage:_ `add_event_listener(event_type: str, callback: Callable[[Any], None], **args) -> int` Adds an event listener with the given callback and args. Supported event types: * `"add_entity"` – [`AddEntityEvent`](https://minescript.net/docs#addentityevent) * `"block_update"` – [`BlockUpdateEvent`](https://minescript.net/docs#blockupdateevent) * `"chat"` – [`ChatEvent`](https://minescript.net/docs#chatevent) * `"chunk"` – [`ChunkEvent`](https://minescript.net/docs#chunkevent) * `"damage"` – [`DamageEvent`](https://minescript.net/docs#damageevent) * `"explosion"` – [`ExplosionEvent`](https://minescript.net/docs#explosionevent) * `"key"` – [`KeyEvent`](https://minescript.net/docs#keyevent) * `"mouse"` – [`MouseEvent`](https://minescript.net/docs#mouseevent) * `"outgoing_chat_intercept"` – [`ChatEvent`](https://minescript.net/docs#chatevent) * `"render"` – [`RenderEvent`](https://minescript.net/docs#renderevent) * `"take_item"` – [`TakeItemEvent`](https://minescript.net/docs#takeitemevent) * `"tick"` – [`TickEvent`](https://minescript.net/docs#tickevent) * `"world"` – [`WorldEvent`](https://minescript.net/docs#worldevent) Compatibility: Pyjinn only. (See [`EventQueue`](https://minescript.net/docs#eventqueue) for Python event handling.) #### remove\_event\_listener _Usage:_ `remove_event_listener(listener_id: int) -> bool` Removes an event listener previously added using [`add_event_listener()`](https://minescript.net/docs#add_event_listener) . Compatibility: Pyjinn only. #### RenderEvent Render event for use with callback to [`add_event_listener()`](https://minescript.net/docs#add_event_listener) . Compatibility: Pyjinn only. type: str # "render" context: Any # Render context provided by the mod loader. time: float #### TickEvent Tick event for use with callback to [`add_event_listener()`](https://minescript.net/docs#add_event_listener) . Compatibility: Pyjinn only. type: str # "tick" time: float #### set\_timeout _Usage:_ `set_timeout(callback: Callable[..., None], timer_millis: int, *args, **kwargs) -> int` Schedules `callback` to be invoked once after `timer_millis` milliseconds. Returns: an integer ID for the callback which can be canceled with [`remove_event_listener()`](https://minescript.net/docs#remove_event_listener) . Compatibility: Pyjinn only. #### set\_interval _Usage:_ `set_interval(callback: Callable[..., None], timer_millis: int, *args, **kwargs) -> int` Schedules `callback` to be invoked every `timer_millis` milliseconds. Returns: an integer ID for the callback which can be canceled with [`remove_event_listener()`](https://minescript.net/docs#remove_event_listener) . Compatibility: Pyjinn only. #### ManagedCallback Wrapper for managing callbacks passed to Java APIs. Example: “\` callback = ManagedCallback(on\_hud\_render) HudRenderCallback.EVENT.register(HudRenderCallback(callback)) \# Cancel after 1 second (1000 milliseconds): set\_timeout(callback.cancel, 1000) “\` Compatibility: Pyjinn only. #### ManagedCallback.\_\_init\_\_ _Usage:_ `ManagedCallback(callback, cancel_on_exception=True, default_value=None)` Creates a managed callback. Args: – `callback`: a callable function or object to manage – `cancel_on_exception`: if the callback raises an exception, cancel the callback – `default_value`: value to return immediately if callback is called after being canceled #### ManagedCallback.cancel _Usage:_ `ManagedCallback.cancel()` Cancels the callback, returning `default_value` if it continues to be called. #### ManagedCallback.\_\_call\_\_ _Usage:_ `ManagedCallback.__call__(*args)` Calls this callback, checking for cancellation. ![](https://pixel.wp.com/g.gif?v=ext&j=1%3A11.3.4&blog=210917203&post=325&tz=-5&srv=minescript.net&host=minescript.net&ref=&fcp=0&rand=0.9129417349307004) --- # Documentation (v2.1) – Minescript [Skip to content](https://minescript.net/docs-v2-1#content) Minescript v2.1 docs -------------------- Table of contents: * [In-game commands](https://minescript.net/docs-v2-1#in-game-commands) * [Command basics](https://minescript.net/docs-v2-1#command-basics) * [General commands](https://minescript.net/docs-v2-1#general-commands) * [Advanced commands](https://minescript.net/docs-v2-1#advanced-commands) * [Python API](https://minescript.net/docs-v2-1#python-api) * [Script input](https://minescript.net/docs-v2-1#script-input) * [Script output](https://minescript.net/docs-v2-1#script-output) * [minescript module](https://minescript.net/docs-v2-1#minescript-module) Previous version: [v2.0](https://minescript.net/docs-v2-0/) Latest version: [latest](https://minescript.net/docs/) 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](https://minescript.net/docs-v2-1#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](https://minescript.net/docs-v2-1#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](https://minescript.net/docs-v2-1#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](https://minescript.net/docs-v2-1#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](https://minescript.net/docs-v2-1#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`](https://minescript.net/docs-v2-1#echo) , [`chat`](https://minescript.net/docs-v2-1#chat) , and [`execute`](https://minescript.net/docs-v2-1#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 From a Python script in the **minescript** folder, import the `minescript` module: import minescript #### execute _Usage:_ `execute(command: str)` Executes the given Minecraft or Minescript 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 still available, but is deprecated and will be removed in a future version._ 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 #### 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. _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()` Gets the local player’s name. Since: v2.1 #### player\_position _Usage:_ `player_position(done_callback=None)` Gets the local player’s position. _Args:_ * `done_callback`: if given, return immediately and call done\_callback(return\_value) asynchronously when return\_value is ready _Returns:_ * If `done_callback` is `None`, returns player’s position as \[x, y, z\] _Example:_ x, y, z = minescript.player_position() #### player\_hand\_items _Usage:_ `player_hand_items(done_callback=None)` Gets the items in the local player’s hands. _Args:_ * `done_callback`: if given, return immediately and call `done_callback(return_value)` asynchronously when return\_value is ready. _Returns:_ * If `done_callback` is `None`, returns items in player’s inventory as list of items where each item is a dict: `{"item": str, "count": int, "nbt": str}` Since: v2.0 #### player\_inventory _Usage:_ `player_inventory(done_callback=None)` Gets the items in the local player’s inventory. _Args:_ * `done_callback`: if given, return immediately and call `done_callback(return_value)` asynchronously when return\_value is ready _Returns:_ * If `done_callback` is `None`, returns items in player’s inventory as list of items where each item is a dict: `{"item": str, "count": int, "nbt": str}` Since: v2.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 #### players _Usage:_ `players()` Gets a list of nearby players and their attributes: name, position, velocity, etc. Since: v2.1 #### entities _Usage:_ `entities()` Gets a list of nearby entities and their attributes: name, position, velocity, etc. 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 call `done_callback(return_value)` asynchronously when return\_value is ready _Returns:_ * if `done_callback` is `None`, returns the block type at (x, y, z) as a string _Example:_ block_type = minescript.getblock(x, y, z) #### 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 call `done_callback(return_value)` asynchronously when return\_value is ready _Returns:_ * if `done_callback` is `None`, 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 all the chunks in the region from (x1, z1) to (x2, z2) are fully loaded. This function is useful for making sure that a region is fully loaded before setting or filling blocks within it. _Args:_ * `done_callback`: if given, return immediately and call `done_callback(return_value)` asynchronously when return\_value is ready _Returns:_ * if `done_callback` is `None`, returns `True` when the requested region is fully loaded. _Examples:_ \[1\] Don’t do any work until the region is done loading (synchronous / blocking call): print("About to wait for region to load...", file=sys.stderr) # Load all chunks within (x, z) bounds (0, 0) and (320, 160): minescript.await_loaded_region(0, 0, 320, 160) print("Region finished loading.", file=sys.stderr) \[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: print("Region loaded ok.", file=sys.stderr) else: print("Region failed to load.", file=sys.stderr) 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) print("Do other work while region loads...", file=sys.stderr) print("Now wait for region to finish loading...", file=stderr) lock.acquire() print("Do more work now that region finished loading...", file=stderr) #### 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. See also [`register_chat_message_interceptor()`](https://minescript.net/docs-v2-1#register_chat_message_interceptor) for swallowing outgoing chat messages. _Args:_ * `listener`: callable that repeatedly accepts a string representing chat messages Since: v2.0 #### 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, `False` otherwise. 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. See also [`register_chat_message_listener()`](https://minescript.net/docs-v2-1#register_chat_message_listener) for non-destructive listening of chat messages. _Args:_ * `interceptor`: callable that repeatedly accepts a string representing chat messages Since: v2.1 #### 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, `False` otherwise. Since: v2.1 ![](https://pixel.wp.com/g.gif?v=ext&j=1%3A11.3.4&blog=210917203&post=169&tz=-5&srv=minescript.net&host=minescript.net&ref=&fcp=0&rand=0.8971521192627039) --- # Documentation (v1.19) – Minescript [Skip to content](https://minescript.net/docs-v1-19#content) Minescript v1.19 docs --------------------- Table of contents: * [In-game commands](https://minescript.net/docs-v1-19#in-game-commands) * [Command basics](https://minescript.net/docs-v1-19#command-basics) * [General commands](https://minescript.net/docs-v1-19#general-commands) * [Advanced commands](https://minescript.net/docs-v1-19#advanced-commands) * [Python API](https://minescript.net/docs-v1-19#python-api) * [Script input](https://minescript.net/docs-v1-19#script-input) * [Script output](https://minescript.net/docs-v1-19#script-output) * [minescript module](https://minescript.net/docs-v1-19#minescript-module) Latest version: [latest](https://minescript.net/docs/) 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](https://minescript.net/docs-v1-19#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]` 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. See [\\paste](https://minescript.net/docs-v1-19#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](https://minescript.net/docs-v1-19#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](https://minescript.net/docs-v1-19#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](https://minescript.net/docs-v1-19#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._ ### 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. 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 When a Minescript Python script prints to standard output (`sys.stdout`), the output text is sent 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!") # 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") 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) ### minescript module From a Python script in the **minescript** folder, import the `minescript` module: import minescript #### player\_position _Usage:_ `player_position(done_callback=None)` Gets the local player’s position. _Args:_ * `done_callback`: if given, return immediately and call done\_callback(return\_value) asynchronously when return\_value is ready _Returns:_ * if `done_callback` is None, returns player’s position as \[x, y, z\] _Example:_ x, y, z = minescript.player_position() #### 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 call `done_callback(return_value)` asynchronously when return\_value is ready _Returns:_ * if done\_callback is None, returns the block type at (x, y, z) as a string _Example:_ block_type = minescript.getblock(x, y, z) #### await\_loaded\_region _Usage:_ `await_loaded_region(x1: int, z1: int, x2: int, z2: int, done_callback=None)` Notifies the caller when all the chunks in the region from (x1, z1) to (x2, z2) are fully loaded. This function is useful for making sure that a region is fully loaded before setting or filling blocks within it. _Args:_ * `done_callback`: if given, return immediately and call `done_callback(return_value)` asynchronously when return\_value is ready _Returns:_ * if done\_callback is None, returns True when the requested region is fully loaded. _Examples:_ \[1\] Don’t do any work until the region is done loading (synchronous / blocking call): print("About to wait for region to load...", file=sys.stderr) # Load all chunks within (x, z) bounds (0, 0) and (320, 160): minescript.await_loaded_region(0, 0, 320, 160) print("Region finished loading.", file=sys.stderr) \[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: print("Region loaded ok.", file=sys.stderr) else: print("Region failed to load.", file=sys.stderr) 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) print("Do other work while region loads...", file=sys.stderr) print("Now wait for region to finish loading...", file=stderr) lock.acquire() print("Do more work now that region finished loading...", file=stderr) ![](https://pixel.wp.com/g.gif?v=ext&j=1%3A11.3.4&blog=210917203&post=306&tz=-5&srv=minescript.net&host=minescript.net&ref=&fcp=0&rand=0.9649292052926659) --- # Documentation (v2.0) – Minescript [Skip to content](https://minescript.net/docs-v2-0#content) Minescript v2.0 docs -------------------- Table of contents: * [In-game commands](https://minescript.net/docs-v2-0#in-game-commands) * [Command basics](https://minescript.net/docs-v2-0#command-basics) * [General commands](https://minescript.net/docs-v2-0#general-commands) * [Advanced commands](https://minescript.net/docs-v2-0#advanced-commands) * [Python API](https://minescript.net/docs-v2-0#python-api) * [Script input](https://minescript.net/docs-v2-0#script-input) * [Script output](https://minescript.net/docs-v2-0#script-output) * [minescript module](https://minescript.net/docs-v2-0#minescript-module) Previous version: [v1.19](https://minescript.net/docs-v1-19/) Latest version: [latest](https://minescript.net/docs/) 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](https://minescript.net/docs-v2-0#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]` 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. See [\\paste](https://minescript.net/docs-v2-0#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](https://minescript.net/docs-v2-0#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](https://minescript.net/docs-v2-0#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](https://minescript.net/docs-v2-0#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`](https://minescript.net/docs-v2-0#echo) , [`chat`](https://minescript.net/docs-v2-0#chat) , and [`exec`](https://minescript.net/docs-v2-0#exec) ). 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.0 this can be written as: minescript.exec("/setblock ~ ~-1 ~ yellow_concrete") **_Note:_** _`exec` has been renamed to `execute` in Minescript v2.1 to avoid confusion with Python’s built-in `exec`._ 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 From a Python script in the **minescript** folder, import the `minescript` module: import minescript #### exec _Usage:_ `exec(command: str)` Executes the given Minecraft or Minescript 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 is named `execute` in Minescript 2.1. The old name is still available in v2.1, but is deprecated and will be removed in a future version._ Since: v2.0 #### 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 #### player\_position _Usage:_ `player_position(done_callback=None)` Gets the local player’s position. _Args:_ * `done_callback`: if given, return immediately and call done\_callback(return\_value) asynchronously when return\_value is ready _Returns:_ * if `done_callback` is None, returns player’s position as \[x, y, z\] _Example:_ x, y, z = minescript.player_position() #### player\_hand\_items _Usage:_ `player_hand_items(done_callback=None)` Gets the items in the local player’s hands. _Args:_ * `done_callback`: if given, return immediately and call `done_callback(return_value)` asynchronously when return\_value is ready. _Returns:_ * If `done_callback` is `None`, returns items in player’s inventory as list of items where each item is a dict: `{"item": str, "count": int, "nbt": str}` Since: v2.0 #### player\_inventory _Usage:_ `player_inventory(done_callback=None)` Gets the items in the local player’s inventory. _Args:_ * `done_callback`: if given, return immediately and call `done_callback(return_value)` asynchronously when return\_value is ready _Returns:_ * If `done_callback` is `None`, returns items in player’s inventory as list of items where each item is a dict: `{"item": str, "count": int, "nbt": str}` Since: v2.0 #### 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 call `done_callback(return_value)` asynchronously when return\_value is ready _Returns:_ * if done\_callback is None, returns the block type at (x, y, z) as a string _Example:_ block_type = minescript.getblock(x, y, z) #### await\_loaded\_region _Usage:_ `await_loaded_region(x1: int, z1: int, x2: int, z2: int, done_callback=None)` Notifies the caller when all the chunks in the region from (x1, z1) to (x2, z2) are fully loaded. This function is useful for making sure that a region is fully loaded before setting or filling blocks within it. _Args:_ * `done_callback`: if given, return immediately and call `done_callback(return_value)` asynchronously when return\_value is ready _Returns:_ * if done\_callback is None, returns True when the requested region is fully loaded. _Examples:_ \[1\] Don’t do any work until the region is done loading (synchronous / blocking call): print("About to wait for region to load...", file=sys.stderr) # Load all chunks within (x, z) bounds (0, 0) and (320, 160): minescript.await_loaded_region(0, 0, 320, 160) print("Region finished loading.", file=sys.stderr) \[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: print("Region loaded ok.", file=sys.stderr) else: print("Region failed to load.", file=sys.stderr) 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) print("Do other work while region loads...", file=sys.stderr) print("Now wait for region to finish loading...", file=stderr) lock.acquire() print("Do more work now that region finished loading...", file=stderr) #### 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 #### 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, `False` otherwise. Since: v2.0 ![](https://pixel.wp.com/g.gif?v=ext&j=1%3A11.3.4&blog=210917203&post=301&tz=-5&srv=minescript.net&host=minescript.net&ref=&fcp=0&rand=0.4388282756969617) --- # Documentation (3.0) – Minescript [Skip to content](https://minescript.net/docs-v3-0#content) Minescript v3.0 docs -------------------- Table of contents: * [In-game commands](https://minescript.net/docs-v3-0#in-game-commands) * [Command basics](https://minescript.net/docs-v3-0#command-basics) * [General commands](https://minescript.net/docs-v3-0#general-commands) * [Advanced commands](https://minescript.net/docs-v3-0#advanced-commands) * [Python API](https://minescript.net/docs-v3-0#python-api) * [Script input](https://minescript.net/docs-v3-0#script-input) * [Script output](https://minescript.net/docs-v3-0#script-output) * [minescript module](https://minescript.net/docs-v3-0#minescript-module) Previous version: [v2.1](https://minescript.net/docs-v2-1) Latest version: [latest](https://minescript.net/docs/) 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](https://minescript.net/docs-v3-0#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](https://minescript.net/docs-v3-0#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](https://minescript.net/docs-v3-0#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](https://minescript.net/docs-v3-0#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](https://minescript.net/docs-v3-0#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`](https://minescript.net/docs-v3-0#echo) , [`chat`](https://minescript.net/docs-v3-0#chat) , and [`execute`](https://minescript.net/docs-v3-0#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` if `message` 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 call `done_callback(return_value)` asynchronously when `return_value` is ready _Returns:_ * if `done_callback` is `None`, 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 call `done_callback(return_value)` asynchronously when `return_value` is ready _Returns:_ * If `done_callback` is `None`, 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 call `done_callback(return_value)` asynchronously when `return_value` is ready _Returns:_ * If `done_callback` is `None`, 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 hotbar * `done_callback`: if given, return immediately and call `done_callback(return_value)` asynchronously when `return_value` is ready _Returns:_ * If `done_callback` is `None`, 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 hand * `done_callback`: if given, return immediately and call `done_callback(return_value)` asynchronously when `return_value` is ready _Returns:_ * If `done_callback` is `None`, 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`: 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:_ * \[\[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 call `done_callback(return_value)` asynchronously when `return_value` is ready _Returns:_ * if `done_callback` is `None`, 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 call `done_callback(return_value)` asynchronously when `return_value` is ready _Returns:_ * if `done_callback` is `None`, 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 call `done_callback(return_value)` asynchronously when `return_value` is ready _Returns:_ * if `done_callback` is `None`, returns `True` 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()`](https://minescript.net/docs-v3-0#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()`](https://minescript.net/docs-v3-0#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`](https://minescript.net/docs-v3-0#blockpack) and [`BlockPacker`](https://minescript.net/docs-v3-0#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](https://minescript.net/docs-v3-0#rotation) , rot2: [Rotation](https://minescript.net/docs-v3-0#rotation) , /) -> [Rotation](https://minescript.net/docs-v3-0#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`](https://minescript.net/docs-v3-0#blockpacker) . Since: v3.0 #### BlockPack.read\_world _Usage:_ `@classmethod BlockPack.read_world(pos1: [BlockPos](https://minescript.net/docs-v3-0#blockpos) , pos2: [BlockPos](https://minescript.net/docs-v3-0#blockpos) , *, rotation: [Rotation](https://minescript.net/docs-v3-0#rotation) = None, offset: [BlockPos](https://minescript.net/docs-v3-0#blockpos) = None, comments: Dict[str, str] = {}, safety_limit: bool = True) -> [BlockPack](https://minescript.net/docs-v3-0#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 _Raises:_ `BlockPackException` if blockpack cannot be read #### BlockPack.read\_file _Usage:_ `@classmethod BlockPack.read_file(filename: str, *, relative_to_cwd=False) -> [BlockPack](https://minescript.net/docs-v3-0#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 _Raises:_ `BlockPackException` if blockpack cannot be read #### BlockPack.import\_data _Usage:_ `@classmethod BlockPack.import_data(base64_data: str) -> [BlockPack](https://minescript.net/docs-v3-0#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](https://minescript.net/docs-v3-0#rotation) = None, offset: [BlockPos](https://minescript.net/docs-v3-0#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) _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`: if `True`, 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(...)`](https://minescript.net/docs-v3-0#blockpackersetblock) , [`fill(...)`](https://minescript.net/docs-v3-0#blockpackerfill) , and/or [`add_blockpack(...)`](https://minescript.net/docs-v3-0#blockpackeradd_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`](https://minescript.net/docs-v3-0#blockpack) . Since: v3.0 #### BlockPacker.\_\_init\_\_ _Usage:_ `BlockPacker()` Creates a new, empty blockpacker. #### BlockPacker.setblock _Usage:_ `BlockPacker.setblock(pos: [BlockPos](https://minescript.net/docs-v3-0#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](https://minescript.net/docs-v3-0#blockpos) , pos2: [BlockPos](https://minescript.net/docs-v3-0#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](https://minescript.net/docs-v3-0#blockpack) , *, rotation: [Rotation](https://minescript.net/docs-v3-0#rotation) = None, offset: [BlockPos](https://minescript.net/docs-v3-0#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) _Raises:_ `BlockPackerException` if blockpacker operation fails #### BlockPacker.pack _Usage:_ `BlockPacker.pack(*, comments: Dict[str, str] = {}) -> [BlockPack](https://minescript.net/docs-v3-0#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 ![](https://pixel.wp.com/g.gif?v=ext&j=1%3A11.3.4&blog=210917203&post=333&tz=-5&srv=minescript.net&host=minescript.net&ref=&fcp=0&rand=0.4803662077589317) ---