Minescript – Python scripting for Minecraft

Minescript 5.0 is now in beta!

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 Use.

Download the Minescript mod at Modrinth or CurseForge, available as a Minecraft mod for Fabric and NeoForge (older versions are available for Forge).

Download featured Python scripts for Minescript.

Join the Minescript Discord for news and updates.

Subscribe to the Minescript channel on YouTube.

Integrated scripting with Pyjinn

Pyjinn (pronounced like “pidgeon”) is an interpreter that recognizes Python syntax and integrates deeply with Java programs. It uses a “pidgin” language that looks and feels like Python while its implementation and runtime behavior are based in Java. (The name “Pyjinn” is a combination of “Python” and “jinn”, which is another word for “genie”.)

Pyjinn is integrated into Minescript 5.0, allowing scripts with Python syntax to be run directly by the Minescript mod without requiring a separate Python installation. Standard Python scripts that run as separate processes continue to be supported. See Pyjinn documentation for details.

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)