World Interaction

/**
 * Get the block at a specific position
 * @param point - World coordinates
 * @param extraInfos - Include additional block metadata
 * @returns Block instance or null if not loaded
 */
blockAt(point: Vec3, extraInfos?: boolean): Block | null;

/**
 * Get the block the bot is looking at within line of sight
 * @param maxSteps - Maximum ray-casting steps
 * @param vectorLength - Length of each ray-casting step
 * @returns Block in sight or null
 */
blockInSight(maxSteps: number, vectorLength: number): Block | null;

/**
 * Get block at cursor position with optional distance and matching
 * @param maxDistance - Maximum search distance
 * @param matcher - Optional block matching function
 * @returns Block at cursor or null
 */
blockAtCursor(maxDistance?: number, matcher?: (block: Block) => boolean): Block | null;

/**
 * Get block at entity's cursor position
 * @param entity - Target entity (defaults to bot)
 * @param maxDistance - Maximum search distance
 * @param matcher - Optional block matching function
 * @returns Block at entity cursor or null
 */
blockAtEntityCursor(entity?: Entity, maxDistance?: number, matcher?: (block: Block) => boolean): Block | null;

/**
 * Check if the bot can see a specific block
 * @param block - Block to check visibility
 * @returns True if block is visible
 */
canSeeBlock(block: Block): boolean;

/**
 * Find the nearest block matching the criteria
 * @param options - Search parameters
 * @returns First matching block or null
 */
findBlock(options: FindBlockOptions): Block | null;

/**
 * Find all blocks matching the criteria within range
 * @param options - Search parameters
 * @returns Array of matching block positions
 */
findBlocks(options: FindBlockOptions): Vec3[];

interface FindBlockOptions {
  /** Starting search point (defaults to bot position) */
  point?: Vec3;
  /** Block type(s) to match or matching function */
  matching: number | number[] | ((block: Block) => boolean);
  /** Maximum search distance in blocks */
  maxDistance?: number;
  /** Maximum number of blocks to find */
  count?: number;
  /** Use extra block information for matching */
  useExtraInfo?: boolean | ((block: Block) => boolean);
}

// Find nearest diamond ore
const diamondOre = bot.findBlock({
  matching: bot.registry.blocksByName.diamond_ore.id,
  maxDistance: 64
});

// Find all wood logs within 32 blocks
const woodLogs = bot.findBlocks({
  matching: (block) => block.name.includes("log"),
  maxDistance: 32,
  count: 50
});

// Find chest with custom criteria
const chest = bot.findBlock({
  matching: bot.registry.blocksByName.chest.id,
  maxDistance: 16,
  useExtraInfo: (block) => {
    // Additional chest validation logic
    return block.light > 5;
  }
});

/**
 * Check if the bot can dig a specific block
 * @param block - Block to check
 * @returns True if block can be dug
 */
canDigBlock(block: Block): boolean;

/**
 * Calculate time required to dig a block
 * @param block - Block to analyze
 * @returns Time in milliseconds
 */
digTime(block: Block): number;

/**
 * Dig/break a block
 * @param block - Block to dig
 * @param forceLook - Force looking at block, or 'ignore' to skip
 * @param digFace - Face to dig from ('auto', Vec3, or 'raycast')
 * @returns Promise that resolves when digging completes
 */
dig(block: Block, forceLook?: boolean | "ignore", digFace?: "auto" | Vec3 | "raycast"): Promise<void>;

/**
 * Stop the current digging operation
 */
stopDigging(): void;

/**
 * Place a block against a reference block
 * @param referenceBlock - Block to place against
 * @param faceVector - Face direction for placement
 * @returns Promise that resolves when placement completes
 */
placeBlock(referenceBlock: Block, faceVector: Vec3): Promise<void>;

/**
 * Activate/right-click a block
 * @param block - Block to activate
 * @param direction - Direction vector for interaction
 * @param cursorPos - Precise cursor position on block face
 * @returns Promise that resolves when activation completes
 */
activateBlock(block: Block, direction?: Vec3, cursorPos?: Vec3): Promise<void>;

/**
 * Update text on a sign block
 * @param block - Sign block to update
 * @param text - New text content (newlines supported)
 * @param back - Update back side of sign (1.20+ hanging signs)
 */
updateSign(block: Block, text: string, back?: boolean): void;

// Basic block digging
const stone = bot.blockAt(bot.entity.position.offset(1, 0, 0));
if (stone && bot.canDigBlock(stone)) {
  console.log(`Digging will take ${bot.digTime(stone)}ms`);
  await bot.dig(stone);
  console.log("Stone mined!");
}

// Place a block
const dirt = bot.inventory.items().find(item => item.name === "dirt");
if (dirt) {
  const referenceBlock = bot.blockAt(bot.entity.position.offset(0, -1, 0));
  if (referenceBlock) {
    await bot.placeBlock(referenceBlock, new Vec3(0, 1, 0));
    console.log("Dirt placed!");
  }
}

// Activate a door
const door = bot.findBlock({
  matching: (block) => block.name.includes("door"),
  maxDistance: 4
});
if (door) {
  await bot.activateBlock(door);
  console.log("Door toggled!");
}

// Update a sign
const sign = bot.findBlock({
  matching: (block) => block.name.includes("sign"),
  maxDistance: 5
});
if (sign) {
  bot.updateSign(sign, "Hello World!\nBot was here");
}

interface Bot {
  /** World state and block access */
  world: world.WorldSync;
}

// World events for monitoring changes
interface BotEvents {
  /** Block changed in the world */
  blockUpdate(oldBlock: Block | null, newBlock: Block): void;
  /** Specific block position updated */
  "blockUpdate:(x, y, z)"(oldBlock: Block | null, newBlock: Block | null): void;
  /** Chunk column loaded */
  chunkColumnLoad(chunkPos: Vec3): void;
  /** Chunk column unloaded */
  chunkColumnUnload(chunkPos: Vec3): void;
}

interface BotEvents {
  /** Observe block break progress from other players */
  blockBreakProgressObserved(block: Block, destroyStage: number): void;
  /** Block break progress ended */
  blockBreakProgressEnd(block: Block): void;
  /** Bot completed digging a block */
  diggingCompleted(block: Block): void;
  /** Bot stopped digging a block */
  diggingAborted(block: Block): void;
}

// Monitor world changes
bot.on("blockUpdate", (oldBlock, newBlock) => {
  if (oldBlock?.name !== newBlock?.name) {
    console.log(`Block changed from ${oldBlock?.name || "air"} to ${newBlock?.name || "air"} at ${newBlock?.position}`);
  }
});

// Track digging progress
bot.on("diggingCompleted", (block) => {
  console.log(`Successfully mined ${block.name} at ${block.position}`);
});

bot.on("diggingAborted", (block) => {
  console.log(`Stopped mining ${block.name} at ${block.position}`);
});

// Monitor other players breaking blocks
bot.on("blockBreakProgressObserved", (block, stage) => {
  console.log(`Block ${block.name} at ${block.position} is ${stage}/10 broken`);
});

interface Block {
  /** Numeric block type ID */
  type: number;
  /** Block name (e.g., "stone", "diamond_ore") */
  name: string;
  /** Block position in world coordinates */
  position: Vec3;
  /** Block metadata/damage value */
  metadata: number;
  /** Block light level */
  light: number;
  /** Sky light level at block */
  skyLight: number;
  /** Block hardness (mining difficulty) */
  hardness: number;
  /** Material category */
  material: string;
  /** Block state properties */
  getProperties(): { [key: string]: any };
  /** Check if block can be harvested with current tool */
  canHarvest(heldItemType?: number): boolean;
  /** Get drops when mined with current tool */
  drops(heldItemType?: number, enchants?: any[]): Item[];
}

interface Vec3 {
  x: number;
  y: number;
  z: number;
  offset(dx: number, dy: number, dz: number): Vec3;
  distanceTo(other: Vec3): number;
  equals(other: Vec3): boolean;
}