botmine 0.1.0

Native Python Minecraft Java bot protocol library.

BotMine

BotMine is a small native Python library for Minecraft Java bots. It is not a Mineflayer wrapper and does not start Node.js.

The first release focuses on a simple Python API and the protocol pieces needed to connect to offline-mode Java servers, read server status, and disconnect cleanly.

Install

pip install botmine

Shortest bot:

import botmine

bot = botmine.Bot("127.0.0.1", 25565, nickname="Bs", version="26.1.2")
bot.reconnect(True)
bot.say("BotMine online")
bot.command("help")
bot.follow_player("wawca")
bot.wait()

Run the bundled example from the project root:

python -m examples.simple

BotMine has no runtime dependencies outside Python itself. requirements.txt is empty on purpose. The package uses only the Python standard library and does not start JavaScript, Node.js, or Mineflayer.

The same thing with with:

import botmine

with botmine.Bot("127.0.0.1", 25565, nickname="Bs", version="26.1.2") as bot:
    bot.say("BotMine online")
    bot.follow_player("wawca")
    bot.wait()

Settings can also be changed through property():

bot = botmine.Bot("127.0.0.1", 25565, auto_connect=False)
bot.property(nickname="Bs", version="26.1.2", auto_swap_tools=True)
bot.connect()
bot.say("Hello from BotMine")
bot.command("/help")
bot.wait(30)
bot.leave()

follow_player() is packet-level movement, not full pathfinding. It follows a visible player while wait() or run_for() is running. It can jump one-block steps, but it is still not full pathfinding.

Events:

def on_chat(player, message):
    if message == "come":
        bot.follow_player(player)

bot.on("chat", on_chat)
bot.on("join", lambda player: print("join", player))
bot.on("leave", lambda player: print("leave", player))
bot.on("death", lambda message: print("death", message))
bot.on("respawn", lambda: print("respawn"))
bot.on("kicked", lambda reason: print("kicked", reason))

Movement:

bot.goto(x=100, y=64, z=-50)
bot.look_at("wawca")
bot.jump()
bot.sprint(True)
bot.sneak(True)
bot.follow_player("wawca")
bot.follow_stop("wawca")
print(bot.position())

Inventory and item actions:

inv = bot.inventory()
bot.equip("diamond_sword")
bot.use_item()
bot.drop("dirt", count=64)
bot.destroy(x=100, y=64, z=-50)
bot.respawn()

The inventory API is a local snapshot from server packets. equip("name") works only after the server has sent a matching tracked slot. auto_swap_tools can select a known hotbar tool before destroy().

Server snapshot:

info = bot.server_info()
print(info["players_count"])
print(info["nearest_player"])
print(info["spawn"])
print(info["time"])

wait() can also take seconds:

bot.wait(4)

Known Java protocol versions are mapped directly for 1.20.1 through 26.1.2. For version="auto" or a future unknown version label, BotMine uses the server status ping to detect the protocol ID before login.

Current limits

• Java Edition protocol only.
• Offline-mode login only. Online-mode/Microsoft authentication is intentionally not faked.
• The library currently handles login/configuration enough for basic connection, chat, simple movement, tracked inventory actions and clean disconnect. Full pathfinding, signed chat sessions and full game-state tracking are not implemented yet.

Release

Build and check the package before uploading:

python -B -m unittest discover -s tests
python -m build
python -m twine check dist/*

Upload to TestPyPI first:

python -m twine upload --repository testpypi dist/*

Then upload to PyPI:

python -m twine upload dist/*