home / skills / bdambrosio / cognitive_workbench / mc-observe-entities

mc-observe-entities skill

safe

This skill enumerates visible entities within a 7-block radius, providing concise summaries and structured data for quick situational awareness.

npx playbooks add skill bdambrosio/cognitive_workbench --skill mc-observe-entities

Review the files below or copy the command above to add this skill to your agents.

Files (2)

Skill.md

2.4 KB

---
name: mc-observe-entities
type: python
description: "Visible entities within radius R (default/max 7), filtered by view cone and line-of-sight."
---

# Minecraft Observe Entities Tool

Enumerates all visible entities (mobs, players, items, etc.) within observation radius. Provides structured summary with pose, entity counts by category and type, nearest entities, and distance-sorted lists.

## Purpose

Visible entity observation for awareness of mobs, players, and items. Returns both human-readable SUMMARY text and machine-readable structured data.

## Input

- `radius`: Optional integer observation radius (default: `7`, max: `7`)
- `entities_radius`: Optional integer observation radius (default: `7`, max: `7`). If both provided, `entities_radius` takes precedence.
- `value`: Ignored

## Output

Returns uniform_return format with:
- `value`: Multi-line SUMMARY text (human-readable, ≤ 1024 chars)
- `data`: Structured observation dict (machine-readable). Key fields:
  - `success`: Boolean
  - `pose`: `{x, y, z, yaw, pitch}` (floats)
  - `entities`: `{total: int, by_category: {string: int}, types: {string: int}, nearest: {string: float}, by_distance: [dict], nearby: [dict]}`
    - Each entry in `entities.nearby` includes: `name`, `type`, `position`, `dx`, `dy`, `dz`, `distance` (items may include `item_name`, `item_count`)
  - `conf`: `"high"` | `"med"` | `"low"`
  - `note`: String (human-readable summary)

## Behavior & Performance

- Enumerates visible entities within radius, filtered by view cone (yaw ±60°, pitch -60..+90) and line-of-sight
- Radius limits: Default 7 blocks, maximum 7 blocks
- Confidence levels: `high` (complete, fast), `med` (complete but slow/many entities), `low` (incomplete observation)
- Entity categorization: Groups entities by category (mob, player, item, other)

## Guidelines

- Use `mc-observe-items` for item-only observation (this tool reports all entity types)
- Use `mc-observe-blocks` for block observation (this tool only reports entities)
- `entities.by_category` provides quick overview of entity types present
- `entities.nearest` shows closest entity of each type
- `conf=low` indicates incomplete observation - may need retry or larger radius
- Raw exhaustive data stored in `data.entities.nearby` for detailed analysis

## Usage Examples

Standard observation:
```json
{"type":"mc-observe-entities","out":"$entities"}
```

With custom radius:
```json
{"type":"mc-observe-entities","radius":7,"out":"$entities"}
```

Overview

This skill enumerates visible entities around the player within a configurable radius (default and maximum 7 blocks). It filters results by view cone and line-of-sight, then returns both a concise human-readable SUMMARY and detailed machine-readable observation data. The output includes counts by category and type, nearest entities, distance-sorted lists, and the observer's pose. Confidence is reported to indicate completeness of the observation.

How this skill works

The skill scans the world for entities within the specified radius, applies a view-cone filter (yaw ±60°, pitch -60°..+90°) and performs line-of-sight checks to exclude occluded entities. It aggregates results into a structured dict with pose, total counts, categorization (mob, player, item, other), nearest-of-type, and a distance-sorted nearby list. A short SUMMARY text (≤1024 chars) is produced for quick human reading while raw details live in entities.nearby for programmatic use. Observation confidence (high/med/low) flags whether the result is complete or may need a retry.

When to use it

Quick situational awareness of mobs, players, and items in front of the observer
Collecting structured entity data for automation or decision logic
Detecting nearby threats or targets while moving or exploring
Debugging AI behaviors that depend on visible entities
Combining with block- or item-specific tools for richer world context

Best practices

Keep radius at or below 7 (default) to ensure fast, accurate scans
Retry observation if conf is low or med to improve completeness
Use mc-observe-items when you only need items to avoid extra data
Combine pose and entities.nearby for precise navigation or targeting
Check entities.by_category first for a quick overview before parsing full lists

Example use cases

Alert if a hostile mob is visible within 7 blocks and in the view cone
Log nearby players and their distances for collaborative tools
Pick up closest dropped item by reading entities.nearest for items
Feed entities.nearby into pathing logic to avoid obstacles or creatures
Generate a short human-readable SUMMARY for HUD display

FAQ

What are the radius limits?

Default and maximum radius are 7 blocks; entities_radius overrides radius when provided.

What does conf=low mean?

conf=low indicates the observation may be incomplete—re-run with the same radius or adjust position to improve line-of-sight.