Mineflex

A native Python implementation of a Minecraft bot framework, inspired by and behaviorally compatible with 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

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 for detailed status.

Installation

pip install mineflex

Documentation

• Getting Started
• Architecture
• API Reference
• Plugin Development
• Authentication
• Version Support

License

MIT License - See LICENSE file

Acknowledgments

Mineflex is inspired by and aims for behavioral compatibility with Mineflayer and the PrismarineJS ecosystem. This is an independent Python implementation, not a translation or wrapper.