Metadata-Version: 2.4
Name: botmine
Version: 0.1.0
Summary: Native Python Minecraft Java bot protocol library.
Author: BotMine contributors
Maintainer: BotMine contributors
License-Expression: MIT
Keywords: minecraft,bot,protocol,java-edition,offline-mode
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# 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

```powershell
pip install botmine
```

Shortest bot:

```python
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:

```powershell
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`:

```python
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()`:

```python
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:

```python
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:

```python
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:

```python
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:

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

`wait()` can also take seconds:

```python
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:

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

Upload to TestPyPI first:

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

Then upload to PyPI:

```powershell
python -m twine upload dist/*
```
