mc-observe_skill

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.