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 in config.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() and players() (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(), and log(), like builtin print() function (114c559)
  • append_chat_history(), chat_input(), and set_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 and help 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"])