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