PySrvSTG

Work in progress. This project is still under active development. You can join, place/break blocks in creative, and spawn some entities, but entities do not work properly yet (interaction, AI, riding, and breeding are incomplete or buggy). Expect breaking changes.

Plugin-first Minecraft Java Edition server in Python. Primary target: 26.2 (protocol 776). Also supports 1.21.11 (774) and 1.21.4 (769). Offline mode by default.

Run

pip install -e ".[dev]"
python -m pysrvstg --config config/server.toml

Connect with Minecraft 26.2, 1.21.11, or 1.21.4 to localhost:25565 (offline mode). The server picks encoders from the client handshake protocol version. See config/server.toml for the pinned version.

Write a plugin

Drop a .py file in plugins/. The server calls on_load() once and on_tick() every game tick (20 TPS).

from pysrvstg import hotbar, players
from pysrvstg.events import PlayerJoinEvent, ChatEvent

def on_tick():
    if PlayerJoinEvent:
        hotbar.broadcast(f"Welcome! {players.count} online")
    if ChatEvent:
        if ChatEvent.message.startswith("!hello"):
            ChatEvent.reply("Hi!")

Event loop style

For a script-style loop in a background thread:

import threading
from pysrvstg import server, hotbar, players
from pysrvstg.events import PlayerJoinEvent

def on_load():
    threading.Thread(target=_loop, daemon=True).start()

def _loop():
    while server.loop():
        if PlayerJoinEvent:
            hotbar.broadcast(f"{players.count} online")

if PlayerJoinEvent: works because events are boolean latches for the current tick (EventSignal.__bool__).

Supported features (current)

• Server list ping (MOTD, player count)
• Login (offline), configuration, play state (26.2 / 1.21.11 / 1.21.4)
• Flat overworld spawn, tab list, loading terrain
• Creative block place/break (server-tracked), basic water/lava flow
• Entity spawn from eggs and some placeables (experimental)
• Action bar (hotbar.send / hotbar.broadcast)
• Chat events (ChatEvent, reply())
• Plugin load errors disable only that plugin

Not included or incomplete: online-mode auth, survival gameplay, proper entity AI and interaction, world save, permissions, redstone, inventories.

Adding Minecraft versions

1. Copy src/pysrvstg/net/protocol/versions/v769.py to vXXX.py using packet IDs from minecraft-data pc/<version>/protocol.json.
2. Implement the VersionProtocol methods (join, chunks, chat, action bar).
3. Register in src/pysrvstg/net/protocol/registry.py (see v774.py as a template) and add a server.toml alias.

Plugins stay unchanged; only the protocol module differs.

Tests

pytest