Bot Management

/**
 * Creates a new bot instance with the specified configuration
 * @param options - Bot configuration options
 * @returns Bot instance ready for connection
 */
function createBot(options: BotOptions): Bot;

interface BotOptions extends ClientOptions {
  /** Bot username (required) */
  username?: string;
  /** Server hostname (default: localhost) */
  host?: string;
  /** Server port (default: 25565) */
  port?: number;
  /** Account password for online mode */
  password?: string;
  /** Minecraft version (auto-detected if false/undefined) */
  version?: string | boolean;
  /** Authentication method */
  auth?: "microsoft" | "mojang" | "offline";
  /** Custom minecraft-protocol client */
  client?: Client;
  /** Enable error logging to console (default: true) */
  logErrors?: boolean;
  /** Hide error messages (default: false) */
  hideErrors?: boolean;
  /** Load internal plugins (default: true) */
  loadInternalPlugins?: boolean;
  /** Plugin configuration */
  plugins?: PluginOptions;
  /** Chat visibility level */
  chat?: ChatLevel;
  /** Enable colored console output (default: true) */
  colorsEnabled?: boolean;
  /** View distance setting */
  viewDistance?: ViewDistance;
  /** Preferred main hand */
  mainHand?: MainHands;
  /** Game difficulty preference */
  difficulty?: number;
  /** Chat message length limit */
  chatLengthLimit?: number;
  /** Enable physics simulation (default: true) */
  physicsEnabled?: boolean;
  /** Maximum physics catchup ticks (default: 4) */
  maxCatchupTicks?: number;
  /** Client brand string */
  brand?: string;
  /** Enable default chat patterns */
  defaultChatPatterns?: boolean;
  /** Auto-respawn on death (default: true) */
  respawn?: boolean;
}

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

interface PluginOptions {
  [plugin: string]: boolean | Plugin;
}

type Plugin = (bot: Bot, options: BotOptions) => void;

import { createBot } from "mineflayer";

// Basic connection
const bot = createBot({
  host: "minecraft.example.com",
  port: 25565,
  username: "MyBot"
});

// Offline mode with custom settings
const offlineBot = createBot({
  host: "localhost",
  username: "TestBot",
  auth: "offline",
  version: "1.20.1",
  physicsEnabled: true,
  viewDistance: "normal"
});

// Online authentication
const onlineBot = createBot({
  host: "server.example.com",
  username: "player@example.com",
  password: "password123",
  auth: "microsoft",
  version: "1.20.4"
});

// Custom plugin configuration
const customBot = createBot({
  username: "CustomBot",
  plugins: {
    inventory: true,
    pathfinder: require("mineflayer-pathfinder").pathfinder,
    chest: false // disable internal chest plugin
  }
});

/**
 * Connect to server (called automatically during bot creation)
 * @param options - Connection options
 */
connect(options: BotOptions): void;

/**
 * Disconnect from server gracefully
 * @param reason - Optional disconnect reason
 */
end(reason?: string): void;

/**
 * Quit the game immediately
 * @param reason - Optional quit reason
 */
quit(reason?: string): void;

/**
 * Respawn after death (if respawn option is disabled)
 */
respawn(): void;

/** Array of all tested Minecraft versions */
const testedVersions: string[];

/** Latest supported Minecraft version */
const latestSupportedVersion: string;

/** Oldest supported Minecraft version */
const oldestSupportedVersion: string;

/**
 * Check if a feature is supported in the specified version
 * @param feature - Feature name to check
 * @param version - Minecraft version string
 * @returns True if feature is supported
 */
function supportFeature(feature: string, version: string): boolean;

/**
 * Load a single plugin
 * @param plugin - Plugin function to load
 */
loadPlugin(plugin: Plugin): void;

/**
 * Load multiple plugins
 * @param plugins - Array of plugin functions
 */
loadPlugins(plugins: Plugin[]): void;

/**
 * Check if a plugin is loaded
 * @param plugin - Plugin function to check
 * @returns True if plugin is loaded
 */
hasPlugin(plugin: Plugin): boolean;

interface Bot {
  /** Bot's username */
  username: string;
  /** Minecraft protocol version */
  protocolVersion: string;
  /** Major Minecraft version */
  majorVersion: string;
  /** Full Minecraft version string */
  version: string;
  /** Bot's entity representation */
  entity: Entity;
  /** Map of all entities by ID */
  entities: { [id: string]: Entity };
  /** Spawn point coordinates */
  spawnPoint: Vec3;
  /** Current game state */
  game: GameState;
  /** Bot's player information */
  player: Player;
  /** Map of all players by username */
  players: { [username: string]: Player };
  /** Minecraft data registry */
  registry: Registry;
  /** Underlying minecraft-protocol client */
  _client: Client;
}

interface GameState {
  /** World generation type */
  levelType: LevelType;
  /** Current game mode */
  gameMode: GameMode;
  /** Hardcore mode flag */
  hardcore: boolean;
  /** Current dimension */
  dimension: Dimension;
  /** Game difficulty */
  difficulty: Difficulty;
  /** Maximum players */
  maxPlayers: number;
  /** Server brand/type */
  serverBrand: string;
}

type LevelType = "default" | "flat" | "largeBiomes" | "amplified" | "customized" | "buffet" | "default_1_1";
type GameMode = "survival" | "creative" | "adventure" | "spectator";
type Dimension = "the_nether" | "overworld" | "the_end";
type Difficulty = "peaceful" | "easy" | "normal" | "hard";

interface BotEvents {
  /** Client connected to server */
  inject_allowed(): void;
  /** Bot logged into server successfully */
  login(): void;
  /** Bot spawned in the game world */
  spawn(): void;
  /** Bot respawned after death */
  respawn(): void;
  /** Game state received from server */
  game(): void;
  /** Bot was kicked from server */
  kicked(reason: string, loggedIn: boolean): void;
  /** Connection ended */
  end(reason: string): void;
  /** Connection or runtime error occurred */
  error(err: Error): void;
}

// Handle connection events
bot.once("login", () => {
  console.log("Logged in successfully!");
});

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

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

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

bot.on("error", (err) => {
  console.error("Bot error:", err);
});