Metadata-Version: 2.4
Name: mineflex
Version: 0.1.0
Summary: A native Python Minecraft bot framework inspired by Mineflayer
Author: Mineflex Contributors
License: MIT
Project-URL: Homepage, https://github.com/yourusername/mineflex
Project-URL: Documentation, https://github.com/yourusername/mineflex/docs
Project-URL: Repository, https://github.com/yourusername/mineflex
Project-URL: Issues, https://github.com/yourusername/mineflex/issues
Keywords: minecraft,bot,mineflayer,minecraft-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: asyncio
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: auth
Requires-Dist: msal>=1.20; extra == "auth"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21; extra == "test"
Dynamic: license-file

# Mineflex

A native Python implementation of a Minecraft bot framework, inspired by and behaviorally compatible with [Mineflayer](https://github.com/PrismarineJS/mineflayer).

## Overview

Mineflex provides a Pythonic API for creating Minecraft bots with asyncio support, designed to offer the same fundamental capabilities and developer experience as Mineflayer while leveraging Python's strengths.

## Target Usage

```python
import asyncio
from mineflex import create_bot

async def main():
    bot = create_bot(
        host="localhost",
        port=25565,
        username="Bot",
        auth="offline",
        version="auto",
    )

    @bot.on("chat")
    async def on_chat(username, message, *args):
        if username != bot.username:
            await bot.chat(message)

    @bot.on("spawn")
    async def on_spawn(*args):
        print("Bot spawned:", bot.username)

    await bot.run()

if __name__ == "__main__":
    asyncio.run(main())
```

## Features

Mineflex aims to provide feature parity with Mineflayer, including:

- Minecraft protocol implementation
- Entity knowledge and tracking
- Block knowledge and world queries
- Physics and movement simulation
- Inventory management
- Crafting, chests, and containers
- Digging and building
- Health, food, and status tracking
- Chat and messaging
- Plugin system for extensibility

## Architecture

Mineflex is designed as a modular, native Python implementation with clear separation of concerns:

- **Protocol Layer**: Minecraft protocol parsing/serialization
- **Client Layer**: Network connection and packet handling
- **World Layer**: Chunks, blocks, biomes, and spatial queries
- **Entity Layer**: Entity tracking and state management
- **Physics Layer**: Movement simulation and collision detection
- **Inventory Layer**: Items, slots, and container management
- **Actions Layer**: Digging, building, combat, and interaction
- **Chat Layer**: Message parsing and component handling
- **Authentication Layer**: Offline and Microsoft authentication
- **Plugin System**: Extensibility and lifecycle management

## Development Status

**Current Status**: Foundation Complete (Phase 7)

Mineflex has completed its foundational implementation with 171 passing unit tests across all major subsystems:

- ✅ Protocol Layer: Codecs, packet definitions, connection handling
- ✅ Client Layer: Connection, keepalive, packet handler
- ✅ World Layer: Chunks, blocks, biomes, heightmaps, spatial queries
- ✅ Entity Layer: Entity tracking, player entities, nearest entity search
- ✅ Physics Layer: Movement simulation, collision detection, gravity
- ✅ Inventory Layer: Items, slots, windows, container management
- ✅ Crafting Layer: Recipe management, crafting feasibility checking
- ✅ Actions Layer: Action primitives (dig, build, use_item, attack)
- ✅ Plugin System: Plugin lifecycle management and extensibility
- ✅ Event System: Async event emitter with handler management

**Limitations**: This is an early implementation. Real-server integration, full protocol support, Microsoft authentication, and many Mineflayer features are not yet implemented. See [docs/COMPATIBILITY_REPORT.md](docs/COMPATIBILITY_REPORT.md) for detailed status.

## Installation

```bash
pip install mineflex
```

## Documentation

- [Getting Started](docs/getting_started.md)
- [Architecture](docs/architecture.md)
- [API Reference](docs/api.md)
- [Plugin Development](docs/plugins.md)
- [Authentication](docs/authentication.md)
- [Version Support](docs/version_support.md)

## License

MIT License - See [LICENSE](LICENSE) file

## Acknowledgments

Mineflex is inspired by and aims for behavioral compatibility with [Mineflayer](https://github.com/PrismarineJS/mineflayer) and the [PrismarineJS](https://github.com/PrismarineJS) ecosystem. This is an independent Python implementation, not a translation or wrapper.
