Minescript 4.0 now available!
Minescript is a platform for controlling and interacting with Minecraft using scripts written in the Python programming language.
Download the Minescript mod at Modrinth or CurseForge, available as a Minecraft mod for Fabric, Forge, and NeoForge.
Download featured Python scripts for Minescript.
Join the Minescript Discord for news and updates.
Updates in Minescript 4.0
- Support running script functions during tick loop (20x per second), render loop (30-100+ fps), or script loop (~5000 times per second) (923f9bb, bfbd192, fb936b8)
- Java reflection via Python script functions, including ability to call script functions from Java (ebdba54, 8008110, 39160c3, 8d97911)
- Introduce Tasks for efficient, synchronous batching of script function calls, including Java reflection (d2bd144, 1377acb, 19eb79c, 0762eaa, 12e7306, f8ed176, 023fd05, 1efbd90, 07388d9)
- Support Python scripts in arbitrary folders using
command_path
inconfig.txt
(791c295, 99c8619, 23ee273) - Support alternative script languages for commands (890d2a9)
- Support for NeoForge, starting with Minecraft 1.20.2 (7dd592f)
- Schedule groups of script functions to run every render or tick cycle with dynamically updated values (19eb79c, 1377acb, d2bd144, 0762eaa)
- Support for scripting several game and input events with a unified
EventQueue
API (d1cb4c9, 6628525, 993c9b6, b96159e, 4af1a32) - Async script functions that are more powerful, easier to use, and cancellable (882bc7e)
- Unified Minescript and Minecraft chat histories when using up/down arrows (46a0cde)
- New and updated script functions, including:
press_key_bind()
(174dac8)show_chat_screen()
(adf8dac)- entity selectors for
entities()
andplayers()
(6d6d627) job_info()
for detecting other running scripts (156dc33)version_info()
for detecting versions of Minecraft, Minescript, and OS (d448c4b)- multiple args to
echo()
,chat()
, andlog()
, like builtinprint()
function (114c559) append_chat_history()
,chat_input()
, andset_chat_input()
for managing chat input and history (46a0cde)player_get_targeted_entity()
(93dd5e8)- Return complex data types from script functions as dataclasses (e.g.
EntityData
) rather than dicts, for easier and safer scripting (7caaf3b) - Support tab completion of
config
andhelp
params (b4bfa0e, f485973) - Safer script output:
print()
no longer executes commands or sends public messages to chat by default (6101484)
See detailed changelog.
Getting started
Place Python scripts (.py
files) in the minecraft/minescript
folder.
These scripts can be run from the Minecraft chat console with a leading
backslash and dropping the .py
. E.g. a file at minecraft/minescript/example.py
can be executed from the Minecraft chat as:
\example
minescript.py
is automatically installed in the minecraft/minescript
folder
the first time that Minecraft launches with the Minescript mod installed. This
Python module contains a library of functions for accessing Minecraft
functionality:
# example.py:
import minescript
# Write a message to the chat that only you can see:
minescript.echo("Hello, world!")
# Write a chat message that other players can see:
minescript.chat("Hello, everyone!")
# Get your player's current position:
x, y, z = minescript.player_position()
# Set the block directly beneath your player:
x, y, z = int(x), int(y), int(z)
minescript.execute(f"setblock {x} {y-1} {z} yellow_concrete")
# Print the type of block at a particular location:
minescript.echo(minescript.getblock(x, y, z))
# Display the contents of your inventory:
for item in minescript.player_inventory():
minescript.echo(item["item"])
# Display the names of nearby entities:
for entity in minescript.entities():
minescript.echo(entity["name"])