home / skills / bdambrosio / cognitive_workbench / mc-observe

mc-observe skill

safe

This skill helps you observe Minecraft world state by fetching blocks, entities, and navigation data in a single efficient API call.

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

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

Files (2)

Skill.md

2.2 KB

---
name: mc-observe
type: python
description: "Unified observation tool: fetches blocks, entities, and items in a single efficient call."
situational: false
---

# Minecraft Unified Observe Tool

Fetches blocks, entities (including items), and navigation surface data in a single HTTP call to the bridge. More efficient than calling mc-observe-blocks, mc-observe-entities, and mc-observe-items separately.

## Purpose

Comprehensive observation for map-building and world awareness. Returns blocks, entities, items, navigation surface, and visibility data in one response.

## Input

- `radius`: Optional integer observation radius (default: `3`, max: `7`)
- `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)
  - `blocks`: `{count, nearby: [dict], nav_surface: [dict], adjacent: dict, visibility_distances: dict, complete: bool, elapsed_ms: int}`
  - `entities`: `{total, items, mobs, players, other, nearby: [dict], complete: bool, elapsed_ms: int, metadata_stats: {with_age, with_velocity, with_persistence}}`
  - `conf`: `"high"` | `"med"` | `"low"`

## Behavior & Performance

- Single HTTP call to `/observe` endpoint with `entity_filter=""` (all entities)
- Returns blocks, entities, items, nav_surface, adjacent_blocks, visibility_distances
- Entity metadata includes age_ticks, velocity, time_until_despawn (if available from Minescript API)
- Logs what data is successfully returned and what is missing (for debugging)
- Radius limits: Default 3 blocks (for testing), maximum 7 blocks
- **Automatically updates persistent spatial map** (calls mc-map-update internally, non-fatal if fails)

## Guidelines

- Use this tool for map-building and comprehensive world observation
- More efficient than calling mc-observe-blocks + mc-observe-entities + mc-observe-items separately
- Entity metadata (age, velocity) may not be available depending on Minescript API version
- Check logs for metadata availability statistics
- Spatial map is automatically updated with each observation (no need to call mc-map-update separately)

Overview

This skill provides a unified observation endpoint that fetches blocks, entities (including item entities), navigation surface, and visibility data in one efficient request. It is designed for building maps and maintaining world awareness without multiple separate calls. The tool automatically updates the persistent spatial map after each observation.

How this skill works

On a single HTTP call to the /observe endpoint (entity_filter=""), the skill returns a structured observation payload containing blocks, entities, items, nav_surface, adjacent blocks, and visibility distances. The response includes a human-readable SUMMARY and a machine-readable data dict with success, pose, detailed blocks and entities sections, confidence level, and timing. It also logs which data were returned or missing and tries to update the spatial map internally (non-fatal if the update fails).

When to use it

When you need comprehensive local world state for map-building or path planning.
When reducing latency and overhead by avoiding multiple observe calls (blocks, entities, items).
When you need navigation surface or visibility data alongside block and entity info.
When you want automatic spatial map updates with each observation.
When collecting entity metadata (age, velocity, despawn time) if available.

Best practices

Specify a radius appropriate to your task (default 3, max 7) to balance detail and performance.
Inspect logs for metadata availability statistics since age/velocity/despawn may be absent depending on the Minescript API version.
Use the machine-readable data dict for programmatic decisions and the SUMMARY for quick human checks.
Treat spatial map updates as best-effort; design workflows that tolerate occasional update failures.
Limit observation frequency to avoid redundant calls since each observation updates the spatial map.

Example use cases

Generate a local tile or chunk map with block types, navigation surface, and adjacent block context in one request.
Detect and classify nearby entities and items for automated pickup, filtering, or avoidance.
Feed visibility distances and nav_surface into pathfinding and movement controllers.
Collect entity metadata (age, velocity) for AI behaviors like despawn-aware item recovery.
Rapidly snapshot a player's local environment for debugging or state synchronization.

FAQ

What radius should I use?

Default radius is 3 for quick tests; use up to 7 for more coverage. Larger radii return more data and take longer to process.

Is entity metadata always available?

No. Age, velocity, and time_until_despawn depend on the Minescript API version and server support. Check logs for metadata availability stats.