Minescript 4.0 now available!
Minescript is a platform for controlling and interacting with Minecraft using scripts written in the Python programming language.
Before using Minescript, please review the Terms of Service.
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.
Subscribe to the Minescript channel on YouTube.
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_stack in minescript.player_inventory():
minescript.echo(item_stack.item)
# Display the names of nearby entities:
for entity in minescript.entities():
minescript.echo(entity.name)