getNearbyEntities

Retrieve a list of all entities within a specified block range in Minecraft, enabling detection of nearby mobs, players, and items for interaction or monitoring purposes.

Instructions

Get a list of all entities nearby

Input Schema

TableJSON Schema

Name	Required	Description	Default
`range`	No	Range in blocks to search for entities

Implementation Reference

src/tools/entityInteraction.ts:23-77 (handler)

The handler function that checks connection, filters nearby entities by distance, groups them by type, formats a detailed list with distances and IDs, and returns a success response.

async ({ range }) => {
  if (!botState.isConnected || !botState.bot) {
    return createNotConnectedResponse()
  }

  try {
    // Get all entities within range
    const nearbyEntities = Object.values(botState.bot.entities).filter(
      (entity) => {
        if (!entity || !entity.position || !botState.bot) return false
        const distance = entity.position.distanceTo(
          botState.bot.entity.position
        )
        return distance <= range && entity.id !== botState.bot.entity.id
      }
    )

    if (nearbyEntities.length === 0) {
      return createSuccessResponse('No entities found nearby.')
    }

    // Group entities by type
    const groupedEntities: Record<string, any[]> = {}
    nearbyEntities.forEach((entity) => {
      const type = String(entity.type || 'unknown')
      if (!groupedEntities[type]) {
        groupedEntities[type] = []
      }
      groupedEntities[type].push(entity)
    })

    // Format the response
    let response = `Entities within ${range} blocks:\n\n`

    for (const [type, entities] of Object.entries(groupedEntities)) {
      response += `${type.toUpperCase()} (${entities.length}):\n`
      entities.forEach((entity: any) => {
        const distance = entity.position
          .distanceTo(botState.bot!.entity.position)
          .toFixed(1)
        const name =
          entity.name ||
          entity.username ||
          entity.displayName ||
          `Entity #${entity.id}`
        response += `- ${name} (${distance} blocks away, ID: ${entity.id})\n`
      })
      response += '\n'
    }

    return createSuccessResponse(response)
  } catch (error) {
    return createErrorResponse(error)
  }
}

src/tools/entityInteraction.ts:16-22 (schema)
Zod schema defining the input parameters for the tool, specifically the optional 'range' parameter defaulting to 10 blocks.
```
{
  range: z
    .number()
    .optional()
    .default(10)
    .describe('Range in blocks to search for entities'),
},
```

src/tools/entityInteraction.ts:13-78 (registration)

The server.tool call that registers the 'getNearbyEntities' tool with its description, input schema, and handler function.

server.tool(
  'getNearbyEntities',
  'Get a list of all entities nearby',
  {
    range: z
      .number()
      .optional()
      .default(10)
      .describe('Range in blocks to search for entities'),
  },
  async ({ range }) => {
    if (!botState.isConnected || !botState.bot) {
      return createNotConnectedResponse()
    }

    try {
      // Get all entities within range
      const nearbyEntities = Object.values(botState.bot.entities).filter(
        (entity) => {
          if (!entity || !entity.position || !botState.bot) return false
          const distance = entity.position.distanceTo(
            botState.bot.entity.position
          )
          return distance <= range && entity.id !== botState.bot.entity.id
        }
      )

      if (nearbyEntities.length === 0) {
        return createSuccessResponse('No entities found nearby.')
      }

      // Group entities by type
      const groupedEntities: Record<string, any[]> = {}
      nearbyEntities.forEach((entity) => {
        const type = String(entity.type || 'unknown')
        if (!groupedEntities[type]) {
          groupedEntities[type] = []
        }
        groupedEntities[type].push(entity)
      })

      // Format the response
      let response = `Entities within ${range} blocks:\n\n`

      for (const [type, entities] of Object.entries(groupedEntities)) {
        response += `${type.toUpperCase()} (${entities.length}):\n`
        entities.forEach((entity: any) => {
          const distance = entity.position
            .distanceTo(botState.bot!.entity.position)
            .toFixed(1)
          const name =
            entity.name ||
            entity.username ||
            entity.displayName ||
            `Entity #${entity.id}`
          response += `- ${name} (${distance} blocks away, ID: ${entity.id})\n`
        })
        response += '\n'
      }

      return createSuccessResponse(response)
    } catch (error) {
      return createErrorResponse(error)
    }
  }
)

MCP Minecraft Remote