Entity Management

/**
 * Find the nearest entity matching the filter criteria
 * @param filter - Optional filter function to match specific entities
 * @returns Nearest matching entity or null
 */
nearestEntity(filter?: (entity: Entity) => boolean): Entity | null;

/**
 * Get the entity at the bot's cursor position
 * @param maxDistance - Maximum search distance
 * @returns Entity at cursor or null
 */
entityAtCursor(maxDistance?: number): Entity | null;

// Find nearest player
const nearestPlayer = bot.nearestEntity(entity => entity.type === "player");

// Find nearest hostile mob
const nearestMob = bot.nearestEntity(entity => 
  ["zombie", "skeleton", "spider", "creeper"].includes(entity.name || "")
);

// Find nearest item entity
const nearestItem = bot.nearestEntity(entity => entity.type === "object");

// Get entity being looked at
const targetEntity = bot.entityAtCursor(10);
if (targetEntity) {
  console.log(`Looking at ${targetEntity.type}: ${targetEntity.username || targetEntity.name}`);
}

/**
 * Attack/hit an entity
 * @param entity - Entity to attack
 */
attack(entity: Entity): void;

/**
 * Right-click/activate an entity
 * @param entity - Entity to activate
 * @returns Promise that resolves when activation completes
 */
activateEntity(entity: Entity): Promise<void>;

/**
 * Activate entity at a specific position on the entity
 * @param entity - Entity to activate
 * @param position - Specific position on entity
 * @returns Promise that resolves when activation completes
 */
activateEntityAt(entity: Entity, position: Vec3): Promise<void>;

/**
 * Use held item on an entity
 * @param targetEntity - Entity to use item on
 */
useOn(targetEntity: Entity): void;

/**
 * Mount/ride an entity
 * @param entity - Entity to mount (horse, boat, minecart, etc.)
 */
mount(entity: Entity): void;

/**
 * Dismount from the current vehicle
 */
dismount(): void;

/**
 * Control vehicle movement
 * @param left - Left strafe amount (-1 to 1)
 * @param forward - Forward movement amount (-1 to 1)
 */
moveVehicle(left: number, forward: number): void;

// Attack nearest zombie
const zombie = bot.nearestEntity(entity => entity.name === "zombie");
if (zombie && zombie.position.distanceTo(bot.entity.position) < 4) {
  bot.attack(zombie);
}

// Right-click a villager to open trading
const villager = bot.nearestEntity(entity => entity.name === "villager");
if (villager) {
  await bot.activateEntity(villager);
}

// Mount a horse
const horse = bot.nearestEntity(entity => entity.name === "horse");
if (horse) {
  bot.mount(horse);
  
  // Control the horse
  bot.moveVehicle(0, 1); // Move forward
  
  // Dismount after some time
  setTimeout(() => {
    bot.dismount();
  }, 5000);
}

// Use saddle on pig
const pig = bot.nearestEntity(entity => entity.name === "pig");
const saddle = bot.inventory.items().find(item => item.name === "saddle");
if (pig && saddle) {
  await bot.equip(saddle, "hand");
  bot.useOn(pig);
}

interface Bot {
  /** Bot's own entity representation */
  entity: Entity;
  /** Map of all loaded entities by ID */
  entities: { [id: string]: Entity };
  /** Map of all players by username */
  players: { [username: string]: Player };
}

interface Entity {
  /** Unique entity ID */
  id: number;
  /** Entity type name */
  type: string;
  /** Entity display name (for named entities) */
  displayName?: ChatMessage;
  /** Position in world coordinates */
  position: Vec3;
  /** Velocity vector */
  velocity: Vec3;
  /** Rotation yaw (horizontal) */
  yaw: number;
  /** Rotation pitch (vertical) */
  pitch: number;
  /** Head yaw (for living entities) */
  headYaw?: number;
  /** Entity height */
  height: number;
  /** Entity width */
  width: number;
  /** Entity health (if applicable) */
  health?: number;
  /** Maximum health (if applicable) */
  maxHealth?: number;
  /** Equipment slots (for living entities) */
  equipment: Item[];
  /** Held item (for living entities) */
  heldItem?: Item;
  /** Entity is valid and loaded */
  isValid: boolean;
  /** Metadata properties */
  metadata: any[];
  /** Entity effects (potions) */
  effects: { [id: number]: { amplifier: number; duration: number } };
}

interface Player extends Entity {
  /** Player UUID */
  uuid: string;
  /** Player username */
  username: string;
  /** Formatted display name */
  displayName: ChatMessage;
  /** Game mode */
  gamemode: number;
  /** Ping latency */
  ping: number;
  /** Associated entity reference */
  entity: Entity;
  /** Skin data */
  skinData?: SkinData;
  /** Profile keys for chat signing */
  profileKeys?: {
    publicKey: Buffer;
    signature: Buffer;
  };
}

interface SkinData {
  /** Skin texture URL */
  url: string;
  /** Skin model type */
  model: string | null;
}

interface BotEvents {
  /** New entity spawned */
  entitySpawn(entity: Entity): void;
  /** Entity removed from world */
  entityGone(entity: Entity): void;
  /** Entity moved to new position */
  entityMoved(entity: Entity): void;
  /** Entity state updated */
  entityUpdate(entity: Entity): void;
  /** Entity attached to vehicle */
  entityAttach(entity: Entity, vehicle: Entity): void;
  /** Entity detached from vehicle */
  entityDetach(entity: Entity, vehicle: Entity): void;
  
  /** Entity performed action */
  entitySwingArm(entity: Entity): void;
  entityHurt(entity: Entity, source: Entity): void;
  entityDead(entity: Entity): void;
  entityEquip(entity: Entity): void;
  entitySleep(entity: Entity): void;
  entityWake(entity: Entity): void;
  entityEat(entity: Entity): void;
  entityCrouch(entity: Entity): void;
  entityUncrouch(entity: Entity): void;
  
  /** Potion effect applied to entity */
  entityEffect(entity: Entity, effect: Effect): void;
  /** Potion effect ended on entity */
  entityEffectEnd(entity: Entity, effect: Effect): void;
  /** Entity attributes changed */
  entityAttributes(entity: Entity): void;
  
  /** Player-specific events */
  playerJoined(player: Player): void;
  playerLeft(player: Player): void;
  playerUpdated(player: Player): void;
  
  /** Item collection events */
  itemDrop(entity: Entity): void;
  playerCollect(collector: Entity, collected: Entity): void;
}

interface Effect {
  /** Effect type ID */
  id: number;
  /** Effect amplifier level */
  amplifier: number;
  /** Remaining duration in ticks */
  duration: number;
}

// Monitor entity spawns
bot.on("entitySpawn", (entity) => {
  console.log(`${entity.type} spawned at ${entity.position}`);
  
  if (entity.type === "player") {
    const player = bot.players[entity.username!];
    console.log(`Player ${player.username} joined the game`);
  }
});

// Track entity deaths
bot.on("entityDead", (entity) => {
  console.log(`${entity.type} died at ${entity.position}`);
});

// Monitor item drops
bot.on("itemDrop", (entity) => {
  console.log(`Item dropped: ${entity.name} at ${entity.position}`);
});

// Track player actions
bot.on("entitySwingArm", (entity) => {
  if (entity.type === "player") {
    console.log(`${entity.username} swung their arm`);
  }
});

// Monitor potion effects
bot.on("entityEffect", (entity, effect) => {
  console.log(`Entity ${entity.type} got effect ${effect.id} level ${effect.amplifier}`);
});

// Access entity information
console.log(`Bot position: ${bot.entity.position}`);
console.log(`Bot health: ${bot.entity.health}/${bot.entity.maxHealth}`);
console.log(`Players online: ${Object.keys(bot.players).length}`);

// Check equipment
const nearbyPlayer = Object.values(bot.players)[0];
if (nearbyPlayer?.entity.equipment[0]) {
  console.log(`${nearbyPlayer.username} is holding: ${nearbyPlayer.entity.equipment[0].name}`);
}

// Common entity filter examples
const isPlayer = (entity: Entity) => entity.type === "player";
const isHostile = (entity: Entity) => ["zombie", "skeleton", "spider", "creeper", "enderman"].includes(entity.name || "");
const isPassive = (entity: Entity) => ["cow", "sheep", "pig", "chicken", "horse"].includes(entity.name || "");
const isItem = (entity: Entity) => entity.type === "object";
const inRange = (maxDistance: number) => (entity: Entity) => 
  entity.position.distanceTo(bot.entity.position) <= maxDistance;

// Usage examples
const nearbyPlayers = Object.values(bot.entities).filter(isPlayer).filter(inRange(20));
const hostileMobs = Object.values(bot.entities).filter(isHostile).filter(inRange(16));
const nearbyItems = Object.values(bot.entities).filter(isItem).filter(inRange(8));