0
# Bot Management
1

2
Core functionality for creating bot instances, managing server connections, and handling bot lifecycle with comprehensive configuration options and plugin system.
3

4
## Capabilities
5

6
### Bot Creation
7

8
Create a bot instance with customizable options for connection, authentication, and behavior.
9

10
```typescript { .api }
11
/**
12
 * Creates a new bot instance with the specified configuration
13
 * @param options - Bot configuration options
14
 * @returns Bot instance ready for connection
15
 */
16
function createBot(options: BotOptions): Bot;
17

18
interface BotOptions extends ClientOptions {
19
  /** Bot username (required) */
20
  username?: string;
21
  /** Server hostname (default: localhost) */
22
  host?: string;
23
  /** Server port (default: 25565) */
24
  port?: number;
25
  /** Account password for online mode */
26
  password?: string;
27
  /** Minecraft version (auto-detected if false/undefined) */
28
  version?: string | boolean;
29
  /** Authentication method */
30
  auth?: "microsoft" | "mojang" | "offline";
31
  /** Custom minecraft-protocol client */
32
  client?: Client;
33
  /** Enable error logging to console (default: true) */
34
  logErrors?: boolean;
35
  /** Hide error messages (default: false) */
36
  hideErrors?: boolean;
37
  /** Load internal plugins (default: true) */
38
  loadInternalPlugins?: boolean;
39
  /** Plugin configuration */
40
  plugins?: PluginOptions;
41
  /** Chat visibility level */
42
  chat?: ChatLevel;
43
  /** Enable colored console output (default: true) */
44
  colorsEnabled?: boolean;
45
  /** View distance setting */
46
  viewDistance?: ViewDistance;
47
  /** Preferred main hand */
48
  mainHand?: MainHands;
49
  /** Game difficulty preference */
50
  difficulty?: number;
51
  /** Chat message length limit */
52
  chatLengthLimit?: number;
53
  /** Enable physics simulation (default: true) */
54
  physicsEnabled?: boolean;
55
  /** Maximum physics catchup ticks (default: 4) */
56
  maxCatchupTicks?: number;
57
  /** Client brand string */
58
  brand?: string;
59
  /** Enable default chat patterns */
60
  defaultChatPatterns?: boolean;
61
  /** Auto-respawn on death (default: true) */
62
  respawn?: boolean;
63
}
64

65
type ChatLevel = "enabled" | "commandsOnly" | "disabled";
66
type ViewDistance = "far" | "normal" | "short" | "tiny" | number;
67
type MainHands = "left" | "right";
68

69
interface PluginOptions {
70
  [plugin: string]: boolean | Plugin;
71
}
72

73
type Plugin = (bot: Bot, options: BotOptions) => void;
74
```
75

76
**Usage Examples:**
77

78
```typescript
79
import { createBot } from "mineflayer";
80

81
// Basic connection
82
const bot = createBot({
83
  host: "minecraft.example.com",
84
  port: 25565,
85
  username: "MyBot"
86
});
87

88
// Offline mode with custom settings
89
const offlineBot = createBot({
90
  host: "localhost",
91
  username: "TestBot",
92
  auth: "offline",
93
  version: "1.20.1",
94
  physicsEnabled: true,
95
  viewDistance: "normal"
96
});
97

98
// Online authentication
99
const onlineBot = createBot({
100
  host: "server.example.com",
101
  username: "player@example.com",
102
  password: "password123",
103
  auth: "microsoft",
104
  version: "1.20.4"
105
});
106

107
// Custom plugin configuration
108
const customBot = createBot({
109
  username: "CustomBot",
110
  plugins: {
111
    inventory: true,
112
    pathfinder: require("mineflayer-pathfinder").pathfinder,
113
    chest: false // disable internal chest plugin
114
  }
115
});
116
```
117

118
### Connection Management
119

120
Manage bot connections and handle connection lifecycle events.
121

122
```typescript { .api }
123
/**
124
 * Connect to server (called automatically during bot creation)
125
 * @param options - Connection options
126
 */
127
connect(options: BotOptions): void;
128

129
/**
130
 * Disconnect from server gracefully
131
 * @param reason - Optional disconnect reason
132
 */
133
end(reason?: string): void;
134

135
/**
136
 * Quit the game immediately
137
 * @param reason - Optional quit reason
138
 */
139
quit(reason?: string): void;
140

141
/**
142
 * Respawn after death (if respawn option is disabled)
143
 */
144
respawn(): void;
145
```
146

147
### Version Information
148

149
Access supported Minecraft versions and feature compatibility.
150

151
```typescript { .api }
152
/** Array of all tested Minecraft versions */
153
const testedVersions: string[];
154

155
/** Latest supported Minecraft version */
156
const latestSupportedVersion: string;
157

158
/** Oldest supported Minecraft version */
159
const oldestSupportedVersion: string;
160

161
/**
162
 * Check if a feature is supported in the specified version
163
 * @param feature - Feature name to check
164
 * @param version - Minecraft version string
165
 * @returns True if feature is supported
166
 */
167
function supportFeature(feature: string, version: string): boolean;
168
```
169

170
### Plugin System
171

172
Load and manage plugins for extended functionality.
173

174
```typescript { .api }
175
/**
176
 * Load a single plugin
177
 * @param plugin - Plugin function to load
178
 */
179
loadPlugin(plugin: Plugin): void;
180

181
/**
182
 * Load multiple plugins
183
 * @param plugins - Array of plugin functions
184
 */
185
loadPlugins(plugins: Plugin[]): void;
186

187
/**
188
 * Check if a plugin is loaded
189
 * @param plugin - Plugin function to check
190
 * @returns True if plugin is loaded
191
 */
192
hasPlugin(plugin: Plugin): boolean;
193
```
194

195
### Bot Properties
196

197
Access core bot properties and state information.
198

199
```typescript { .api }
200
interface Bot {
201
  /** Bot's username */
202
  username: string;
203
  /** Minecraft protocol version */
204
  protocolVersion: string;
205
  /** Major Minecraft version */
206
  majorVersion: string;
207
  /** Full Minecraft version string */
208
  version: string;
209
  /** Bot's entity representation */
210
  entity: Entity;
211
  /** Map of all entities by ID */
212
  entities: { [id: string]: Entity };
213
  /** Spawn point coordinates */
214
  spawnPoint: Vec3;
215
  /** Current game state */
216
  game: GameState;
217
  /** Bot's player information */
218
  player: Player;
219
  /** Map of all players by username */
220
  players: { [username: string]: Player };
221
  /** Minecraft data registry */
222
  registry: Registry;
223
  /** Underlying minecraft-protocol client */
224
  _client: Client;
225
}
226

227
interface GameState {
228
  /** World generation type */
229
  levelType: LevelType;
230
  /** Current game mode */
231
  gameMode: GameMode;
232
  /** Hardcore mode flag */
233
  hardcore: boolean;
234
  /** Current dimension */
235
  dimension: Dimension;
236
  /** Game difficulty */
237
  difficulty: Difficulty;
238
  /** Maximum players */
239
  maxPlayers: number;
240
  /** Server brand/type */
241
  serverBrand: string;
242
}
243

244
type LevelType = "default" | "flat" | "largeBiomes" | "amplified" | "customized" | "buffet" | "default_1_1";
245
type GameMode = "survival" | "creative" | "adventure" | "spectator";
246
type Dimension = "the_nether" | "overworld" | "the_end";
247
type Difficulty = "peaceful" | "easy" | "normal" | "hard";
248
```
249

250
## Connection Events
251

252
```typescript { .api }
253
interface BotEvents {
254
  /** Client connected to server */
255
  inject_allowed(): void;
256
  /** Bot logged into server successfully */
257
  login(): void;
258
  /** Bot spawned in the game world */
259
  spawn(): void;
260
  /** Bot respawned after death */
261
  respawn(): void;
262
  /** Game state received from server */
263
  game(): void;
264
  /** Bot was kicked from server */
265
  kicked(reason: string, loggedIn: boolean): void;
266
  /** Connection ended */
267
  end(reason: string): void;
268
  /** Connection or runtime error occurred */
269
  error(err: Error): void;
270
}
271
```
272

273
**Usage Examples:**
274

275
```typescript
276
// Handle connection events
277
bot.once("login", () => {
278
  console.log("Logged in successfully!");
279
});
280

281
bot.once("spawn", () => {
282
  console.log("Bot spawned at:", bot.entity.position);
283
  console.log("Game mode:", bot.game.gameMode);
284
  console.log("Dimension:", bot.game.dimension);
285
});
286

287
bot.on("kicked", (reason, loggedIn) => {
288
  console.log(`Kicked from server: ${reason}`);
289
  if (loggedIn) {
290
    console.log("Was logged in when kicked");
291
  }
292
});
293

294
bot.on("end", (reason) => {
295
  console.log(`Connection ended: ${reason}`);
296
});
297

298
bot.on("error", (err) => {
299
  console.error("Bot error:", err);
300
});
301
```