# prismarinejs/mineflayer architecture

> Architecture diagram of the GitHub repository prismarinejs/mineflayer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prismarinejs/mineflayer
- Repository: https://github.com/prismarinejs/mineflayer

## Overview

Mineflayer is a JavaScript library for creating high-level Minecraft bots. The principal workflow is for an application to create a bot, connect it to a Minecraft server, and use its API to observe world state and perform actions. Internal plugins provide distinct capabilities including world/block queries, entity tracking, movement, digging/building, inventory and crafting, chat, and game-state features. The loader and shared conversion/task utilities form the internal layer. Some plugin details are unsampled; capability coverage and plugin names rely on the README and loader index.

Main entry points: [`lib/loader.js`](https://github.com/prismarinejs/mineflayer/blob/master/lib/loader.js) (Bot loader), [`lib/promise_utils.js`](https://github.com/prismarinejs/mineflayer/blob/master/lib/promise_utils.js) (Async task utilities), [`lib/plugins/physics.js`](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/physics.js) (Physics and movement), [`lib/plugins/entities.js`](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/entities.js) (Entity tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Bot entry"]
  node_mineflayer["Mineflayer API<br/>[index.js]"]
  node_loader["Bot loader<br/>[loader.js]"]
  node_plugin_loader["Plugin loader<br/>[plugin_loader.js]"]
end

subgraph group_world["World model"]
  node_blocks["Blocks and world<br/>[blocks.js]"]
  node_entities["Entity tracking<br/>[entities.js]"]
end

subgraph group_actions["Bot actions"]
  node_physics["Physics and movement<br/>[physics.js]"]
  node_digging["Digging<br/>[digging.js]"]
  node_block_actions["Block actions<br/>[block_actions.js]"]
  node_place_block["Building and placement<br/>[place_block.js]"]
  node_inventory["Inventory<br/>[inventory.js]"]
  node_craft["Crafting<br/>[craft.js]"]
end

subgraph group_state["Game state"]
  node_chat["Chat<br/>[chat.js]"]
  node_game["Game state<br/>[game.js]"]
  node_villager["Trading<br/>[villager.js]"]
  node_scoreboard["Scoreboard<br/>[scoreboard.js]"]
  node_team["Teams<br/>[team.js]"]
end

subgraph group_internal["Internal utilities"]
  node_conversions["Protocol conversions<br/>[conversions.js]"]
  node_promise_utils["Async task utilities<br/>[promise_utils.js]"]
end

node_application(("Bot application"))
node_server(("Minecraft server"))

node_application -->|"uses API"| node_mineflayer
node_mineflayer -->|"exports"| node_loader
node_loader -->|"uses"| node_plugin_loader
node_loader -->|"creates client"| node_server
node_loader -->|"loads plugin"| node_blocks
node_loader -->|"loads plugin"| node_entities
node_loader -->|"loads plugin"| node_physics
node_loader -->|"loads plugin"| node_digging
node_loader -->|"loads plugin"| node_block_actions
node_loader -->|"loads plugin"| node_inventory
node_loader -->|"loads plugin"| node_craft
node_loader -->|"loads plugin"| node_chat
node_loader -->|"loads plugin"| node_game
node_loader -->|"loads plugin"| node_villager
node_loader -->|"loads plugin"| node_scoreboard
node_loader -->|"loads plugin"| node_team
node_entities -->|"converts packets"| node_conversions
node_physics -->|"converts coordinates"| node_conversions
node_physics -->|"uses tasks"| node_promise_utils
node_digging -->|"uses tasks"| node_promise_utils
node_inventory -->|"uses tasks"| node_promise_utils
node_inventory -->|"converts coordinates"| node_conversions
node_craft -->|"uses tasks"| node_promise_utils
node_chat -->|"uses tasks"| node_promise_utils
node_villager -->|"uses tasks"| node_promise_utils
node_scoreboard -->|"uses team map"| node_team
node_blocks -->|"receives updates"| node_server
node_entities -->|"receives updates"| node_server
node_physics -->|"sends movement"| node_server
node_digging -->|"queries world"| node_blocks
node_application -.->|"builds"| node_place_block

click node_mineflayer "https://github.com/prismarinejs/mineflayer/blob/master/index.js"
click node_loader "https://github.com/prismarinejs/mineflayer/blob/master/lib/loader.js"
click node_plugin_loader "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugin_loader.js"
click node_blocks "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/blocks.js"
click node_entities "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/entities.js"
click node_physics "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/physics.js"
click node_digging "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/digging.js"
click node_block_actions "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/block_actions.js"
click node_place_block "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/place_block.js"
click node_inventory "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/inventory.js"
click node_craft "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/craft.js"
click node_chat "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/chat.js"
click node_game "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/game.js"
click node_villager "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/villager.js"
click node_scoreboard "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/scoreboard.js"
click node_team "https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/team.js"
click node_conversions "https://github.com/prismarinejs/mineflayer/blob/master/lib/conversions.js"
click node_promise_utils "https://github.com/prismarinejs/mineflayer/blob/master/lib/promise_utils.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mineflayer,node_loader,node_plugin_loader toneBlue
class node_blocks,node_entities toneAmber
class node_physics,node_digging,node_block_actions,node_place_block,node_inventory,node_craft,node_server toneMint
class node_chat,node_game,node_villager,node_scoreboard,node_team toneRose
class node_conversions,node_promise_utils,node_application toneIndigo
```

## Components

### Bot entry

- [Mineflayer API](https://github.com/prismarinejs/mineflayer/blob/master/index.js): `index.js`
- [Bot loader](https://github.com/prismarinejs/mineflayer/blob/master/lib/loader.js): `lib/loader.js`
- [Plugin loader](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugin_loader.js): `lib/plugin_loader.js`

### World model

- [Blocks and world](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/blocks.js): `lib/plugins/blocks.js`
- [Entity tracking](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/entities.js): `lib/plugins/entities.js`

### Bot actions

- [Physics and movement](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/physics.js): `lib/plugins/physics.js`
- [Digging](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/digging.js): `lib/plugins/digging.js`
- [Block actions](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/block_actions.js): `lib/plugins/block_actions.js`
- [Building and placement](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/place_block.js): `lib/plugins/place_block.js`
- [Inventory](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/inventory.js): `lib/plugins/inventory.js`
- [Crafting](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/craft.js): `lib/plugins/craft.js`

### Game state

- [Chat](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/chat.js): `lib/plugins/chat.js`
- [Game state](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/game.js): `lib/plugins/game.js`
- [Trading](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/villager.js): `lib/plugins/villager.js`
- [Scoreboard](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/scoreboard.js): `lib/plugins/scoreboard.js`
- [Teams](https://github.com/prismarinejs/mineflayer/blob/master/lib/plugins/team.js): `lib/plugins/team.js`

### Internal utilities

- [Protocol conversions](https://github.com/prismarinejs/mineflayer/blob/master/lib/conversions.js): `lib/conversions.js`
- [Async task utilities](https://github.com/prismarinejs/mineflayer/blob/master/lib/promise_utils.js): `lib/promise_utils.js`

### Other components

- **Bot application**
- **Minecraft server**

## Connections

- Bot application → Mineflayer API: uses API
- Mineflayer API → Bot loader: exports (evidence: `index.js`)
- Bot loader → Plugin loader: uses (evidence: `lib/loader.js`)
- Bot loader → Minecraft server: creates client (evidence: `lib/loader.js`)
- Bot loader → Blocks and world: loads plugin (evidence: `lib/loader.js`)
- Bot loader → Entity tracking: loads plugin (evidence: `lib/loader.js`)
- Bot loader → Physics and movement: loads plugin (evidence: `lib/loader.js`)
- Bot loader → Digging: loads plugin (evidence: `lib/loader.js`)
- Bot loader → Block actions: loads plugin (evidence: `lib/loader.js`)
- Bot loader → Inventory: loads plugin (evidence: `lib/loader.js`)
- Bot loader → Crafting: loads plugin (evidence: `lib/loader.js`)
- Bot loader → Chat: loads plugin (evidence: `lib/loader.js`)
- Bot loader → Game state: loads plugin (evidence: `lib/loader.js`)
- Bot loader → Trading: loads plugin (evidence: `lib/loader.js`)
- Bot loader → Scoreboard: loads plugin (evidence: `lib/loader.js`)
- Bot loader → Teams: loads plugin (evidence: `lib/loader.js`)
- Entity tracking → Protocol conversions: converts packets (evidence: `lib/plugins/entities.js`)
- Physics and movement → Protocol conversions: converts coordinates (evidence: `lib/plugins/physics.js`)
- Physics and movement → Async task utilities: uses tasks (evidence: `lib/plugins/physics.js`)
- Digging → Async task utilities: uses tasks (evidence: `lib/plugins/digging.js`)
- Inventory → Async task utilities: uses tasks (evidence: `lib/plugins/inventory.js`)
- Inventory → Protocol conversions: converts coordinates (evidence: `lib/plugins/inventory.js`)
- Crafting → Async task utilities: uses tasks (evidence: `lib/plugins/craft.js`)
- Chat → Async task utilities: uses tasks (evidence: `lib/plugins/chat.js`)
- Trading → Async task utilities: uses tasks (evidence: `lib/plugins/villager.js`)
- Scoreboard → Teams: uses team map
- Blocks and world → Minecraft server: receives updates (evidence: `lib/plugins/blocks.js`)
- Entity tracking → Minecraft server: receives updates (evidence: `lib/plugins/entities.js`)
- Physics and movement → Minecraft server: sends movement (evidence: `lib/plugins/physics.js`)
- Digging → Blocks and world: queries world (evidence: `lib/plugins/digging.js`)
- Bot application → Building and placement: builds
