home / skills / bdambrosio / cognitive_workbench / mc-status

mc-status skill

safe

This skill provides fast Minecraft bot status checks, returning position, orientation, health, hunger, action, and vertical movement state for quick monitoring.

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

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

Files (3)

Skill.md

2.1 KB

---
name: mc-status
type: python
description: "Fast heartbeat + sanity check for Minecraft bot. Returns connection status, position, orientation, health, food (hunger), current action, and vertical_state (derived from Y position changes). Use to check position, orientation, or other status values"
situational: true
---

# Minecraft Status Tool

Fast heartbeat and sanity check for Minecraft bot. Returns connection status, position, orientation, health, food (hunger), current action, and vertical_state.

## Purpose

Quick status check for bot state. Returns both human-readable status text and machine-readable structured data including position, orientation, health, food, and vertical movement state.

## Input

- `value`: Ignored unless `"double_sample"`
  - `"double_sample"`: Take two samples (delay ~0.2s) and compute `vertical_state` immediately

## Output

Returns uniform_return format with:
- `value`: Multi-line status text (human-readable)
- `data`: Structured status dict (machine-readable). Key fields:
  - `position`: `{x, y, z}` (floats)
  - `yaw`: Degrees, normalized to 0–360
  - `pitch`: Degrees
  - `health`: 0–20
  - `food`: 0–20
  - `action`: Dict (may be empty)
  - `vertical_state`: `"STABLE"` | `"FALLING"` | `"UNKNOWN"`
  - `vertical_state_explanation`: String
  - `vertical_state_mode`: `"cached"` | `"double_sample"` | `"auto_double_sample"` | `"single"`
  - `success`: Boolean

## Behavior & Performance

- Fast status check with minimal latency
- Vertical state detection: Uses Y position changes to determine if bot is falling, stable, or unknown
- Double sample mode: When `value="double_sample"`, takes two samples with delay to compute vertical_state immediately

## Guidelines

- Use for periodic health checks and state monitoring
- Use double_sample mode when immediate vertical_state detection is needed
- Vertical_state helps detect falling conditions for safety

## Usage Examples

Standard status check:
```json
{"type":"mc-status","out":"$status"}
```

With double sample for immediate vertical_state:
```json
{"type":"mc-status","value":"double_sample","out":"$status"}
```

Overview

This skill provides a fast heartbeat and sanity check for a Minecraft bot. It returns both a human-readable status summary and structured machine-readable data including connection state, position, orientation, health, hunger, current action, and vertical movement state. Use it to quickly verify the bot is connected and safe.

How this skill works

The skill samples the bot state and builds a status string plus a structured dict with keys like position, yaw, pitch, health, food, action, and vertical_state. Vertical state is derived from changes in Y position; a special "double_sample" mode takes two samples (~0.2s apart) to compute vertical_state immediately. The output includes normalized yaw (0–360), health/food (0–20), an action object, and a clear success flag.

When to use it

Periodic heartbeat to confirm bot connectivity and basic health
Monitoring position and orientation for automation or telemetry
Detecting falls or unsafe vertical movement using vertical_state
Quick sanity checks before running high-risk actions (e.g., teleport, automation)
Use double_sample when you need immediate, reliable vertical movement detection

Best practices

Run the status check frequently but avoid excessive polling to reduce server load
Use value="double_sample" when immediate vertical_state is critical (fall detection)
Interpret vertical_state and vertical_state_explanation together for decisions
Combine structured data with logs or alerts for automated monitoring
Treat action dict as optional; check for empty action before acting

Example use cases

Heartbeat in an automation loop to confirm connection and health before tasks
Safety check before starting movement-heavy behaviors to avoid falls
Dashboard telemetry showing position, yaw/pitch, health, and hunger
Trigger alarms or abort routines when vertical_state reports FALLING
Collect periodic snapshots for debugging pathfinding or player interactions

FAQ

What does vertical_state mean?

vertical_state classifies vertical movement as STABLE, FALLING, or UNKNOWN based on Y position changes; explanation and mode are included for context.

When should I use double_sample?

Use double_sample when you need immediate, accurate vertical_state detection (it samples twice with a short delay to compute vertical movement).