Skip to main content

st_minecraft

(Eine deutsche Version dieser README ist in der Datei README_DE.md verfügbar. Beachten Sie, dass die englische Version die Hauptversion ist. Die deutsche Version könnte veraltet sein.)

2026-09-12_22-04-55_3

(Python Code that modifies player speed based on what block player looks at, part of demo/spiderman.py)

Library for interacting with a Minecraft server through Python programs. This is the frontend part, which requires the use of our Server Plugin on the server side.

(You need to ensure that major and minor tag of plugin and library release must match! e.g. both must be v1.1.x)

The library is designed to teach children the Python programming language playfully through interactions with Minecraft. It is not intended for production use!

We provide an english and a german version of the library.

Quick Example

import st_minecraft.en as mc
from st_minecraft.en.material import MaterialCollection

mc.connect("localhost")

while True:
  player = mc.get_player_by_name("YourPlayerName")
  mc.set_block(player.x, player.y - 1, player.z, MaterialCollection.Diamond_Block)
import st_minecraft.de as mc

mc.verbinden("localhost")

while True:
  spieler = mc.hole_spieler_durch_name("DeinSpielerName")
  mc.setze_block(spieler.x, spieler.y - 1, spieler.z, mc.MaterialSammlung.Stein)

If you're completely new to Python and programming: don't worry. Just follow the steps below and copy the example. You should see first results in a few minutes.

Available Interactions

  • Interact with players
    • fetch information about player (position, stats, inventory)
    • modify player position (incl. dimension and rotation)
    • modify player stats (xp, health, hunger)
    • give items
  • Interact with Blocks
    • Set Blocks
    • Fetch Blocks
  • Send and receive chat messages and execute commands
  • Spawn and edit entities (mobs, items, etc.)
  • Create and edit boss bars
  • Display titles

How to install

What You Need

  • A Minecraft Java Edition server with the appropriate server plugin running. More information can be found in the documentation of the Server Plugin. If the server has been set up for you, you need the IP and port.
  • Python 3.10 or newer on your computer. If not yet installed: download and install from https://www.python.org/downloads/.
    • Make sure to add Python to "PATH" during installation.
  • We also recommend using PyCharm, the free version without subscription is completely sufficient!

Installation with pip

(Optional) Using a virtual eenvironment

We recommend to us a venv: Windows:

py -m venv venv
venv\Scripts\Activate.ps1

Linux/MacOS:

python3 -m venv venv
venv/bin/activate

Installing the library

You can install the library using pip:

pip install st-minecraft

You can find available versions here: https://pypi.org/project/st-minecraft/

Quickstart (copy & paste)

Examples of how to use the library can be found in demo/.

How the Library is Structured

The function names are available in german and english and kept beginner-friendly:

English examples

  • Blocks: set_block(...), get_block(...)
  • Players: get_player(...), set_player_position(...), set_player_health(...), set_player_hunger(...), set_player_xp_level(...), set_player_velocity(...)
  • Chat & Commands: send_to_chat(...), send_command(...)
  • Entities: spawn_entity(...), set_entity_name(...), set_entity_position(...), set_entity_ai(...)
  • Inventory: give_item(...), get_inventory(...)

Block and entity types come from the English enums MaterialCollection and EntityCollection (e.g., MaterialCollection.Melon, EntityCollection.Sheep).

German examples

  • Blocks: setze_block(...), hole_block(...)
  • Players: hole_spieler(...), spieler_position_setzen(...), spieler_leben_setzen(...), spieler_hunger_setzen(...), spieler_xp_level_setzen(...), spieler_geschwindigkeit_setzen(...)
  • Chat & Commands: sende_an_chat(...), sende_befehl(...)
  • Entities: erzeuge_entity(...), entity_name_setzen(...), entity_position_setzen(...), entity_ai_setzen(...)
  • Inventory: gebe_item(...), hole_inventar(...)

Block and entity types come from the German enums MaterialSammlung and EntitySammlung (e.g., MaterialSammlung.Melone, EntitySammlung.Schaf).

Troubleshooting

  • RuntimeError: "No connection to server. Please connect first."
    • First call connect(HOST). Check the servers IP and whether the server is running.
  • Timeout/No response from server
    • The server may not be reachable or the backend is not running. Also check IP and port.
  • I don't know my coordinates (x, y, z)
    • Stand at the desired location in the game and press F3 to see your position. Alternatively, start with small test coordinates near the spawn.

AI Disclaimer

  • Parts of the README and code have been translated using AI.
  • All content has been reviewed by humans before publication.
  • The logic itself was written by hand.

Metadata

Release files for st-minecraft 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for st-minecraft 1.3.0
File Size Uploaded Provenance Actions
st_minecraft-1.3.0.tar.gz 91.8 kB Without provenance Details for st_minecraft-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for st-minecraft 1.3.0
File Interpreter ABI Platform Actions
st_minecraft-1.3.0-py3-none-any.whl Python 3 none any Details for st_minecraft-1.3.0-py3-none-any.whl

Total release size: 184.5 kB

Release files / st_minecraft-1.3.0.tar.gz

Download URL st_minecraft-1.3.0.tar.gz
Size 91.8 kB
Tags Source
SHA-256 checksum
How to use checksums
71dfb0a8972e5439b783be069c7ff232a1b032a98d0c094b7be236ba609da125
BLAKE2b-256 checksum
How to use checksums
b1d17c4cd9f84a387488ff3a4341d8ccb6db7cccc7b94476cb34a5fdd002b043
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.7

Release files / st_minecraft-1.3.0-py3-none-any.whl

Download URL st_minecraft-1.3.0-py3-none-any.whl
Size 92.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bd5064b0eec3a5f03070adc14d51257644ec2c12b6f613e27a10a2c20be8c688
BLAKE2b-256 checksum
How to use checksums
baf3e4daf7700afae90d4a69566574d9ddda36fc81d4c19cf146877943638b8b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.7

Security for st-minecraft 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page