find-entity
Locate the nearest entity of a specified type in Minecraft, such as mobs or items, within a defined search radius to interact with or avoid game elements.
Instructions
Find the nearest entity of a specific type
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Type of entity to find (empty for any entity) | |
| maxDistance | No | Maximum search distance (default: 16) |
Implementation Reference
- src/tools/entity-tools.ts:15-32 (handler)The core handler function for the 'find-entity' tool. It uses the bot's nearestEntity method with a type filter and checks if within maxDistance, returning entity details or a message if none found.
async ({ type = '', maxDistance = 16 }) => { const bot = getBot(); const entityFilter = (entity: NonNullable<Entity>) => { if (!type) return true; if (type === 'player') return entity.type === 'player'; if (type === 'mob') return entity.type === 'mob'; return Boolean(entity.name && entity.name.includes(type.toLowerCase())); }; const entity = bot.nearestEntity(entityFilter); if (!entity || bot.entity.position.distanceTo(entity.position) > maxDistance) { return factory.createResponse(`No ${type || 'entity'} found within ${maxDistance} blocks`); } const entityName = entity.name || (entity as { username?: string }).username || entity.type; return factory.createResponse(`Found ${entityName} at position (${Math.floor(entity.position.x)}, ${Math.floor(entity.position.y)}, ${Math.floor(entity.position.z)})`); } - src/tools/entity-tools.ts:11-14 (schema)Input schema definition using Zod for the tool's parameters: optional 'type' string and 'maxDistance' number.
{ type: z.string().optional().describe("Type of entity to find (empty for any entity)"), maxDistance: z.number().optional().describe("Maximum search distance (default: 16)") }, - src/tools/entity-tools.ts:8-33 (registration)Registers the 'find-entity' tool with the ToolFactory, including name, description, schema, and handler function.
factory.registerTool( "find-entity", "Find the nearest entity of a specific type", { type: z.string().optional().describe("Type of entity to find (empty for any entity)"), maxDistance: z.number().optional().describe("Maximum search distance (default: 16)") }, async ({ type = '', maxDistance = 16 }) => { const bot = getBot(); const entityFilter = (entity: NonNullable<Entity>) => { if (!type) return true; if (type === 'player') return entity.type === 'player'; if (type === 'mob') return entity.type === 'mob'; return Boolean(entity.name && entity.name.includes(type.toLowerCase())); }; const entity = bot.nearestEntity(entityFilter); if (!entity || bot.entity.position.distanceTo(entity.position) > maxDistance) { return factory.createResponse(`No ${type || 'entity'} found within ${maxDistance} blocks`); } const entityName = entity.name || (entity as { username?: string }).username || entity.type; return factory.createResponse(`Found ${entityName} at position (${Math.floor(entity.position.x)}, ${Math.floor(entity.position.y)}, ${Math.floor(entity.position.z)})`); } ); - src/main.ts:54-54 (registration)Top-level invocation of registerEntityTools in the main application, which registers the 'find-entity' tool among others.
registerEntityTools(factory, getBot); - src/tools/entity-tools.ts:5-5 (helper)Type definition for Entity used in the handler's filter function.
type Entity = ReturnType<Bot['nearestEntity']>;