home / skills / bdambrosio / cognitive_workbench / mc-waypoint

mc-waypoint skill

safe

This skill labels a Minecraft coordinate with a named waypoint for easy navigation and spatial reasoning across sessions.

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

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

Files (2)

Skill.md

2.0 KB

---
name: mc-waypoint
type: python
description: "Labels a coordinate with a waypoint name for reasoning about spatial relationships. Use to mark important locations for navigation and planning"
---

# Minecraft Waypoint Tool

Labels a coordinate with a waypoint name for reasoning about spatial relationships. Stores waypoints in persistent spatial memory.

## Purpose

Spatial memory labeling for navigation and planning. Creates named waypoints that can be queried later for navigation and spatial reasoning.

## Input

- `name`: Waypoint name string (required)
- `dx`, `dy`, `dz`: World-relative offsets from agent (optional - defaults to 0,0,0 = current position)
  - See coordinate system documentation in jill-minecraft.yaml for details
- `value`: Ignored

## Output

Returns uniform_return format with:
- `value`: Text summary (success message with waypoint name and location)
- `data`: Structured data dict (machine-readable). Key fields:
  - `waypoint`: String (waypoint name)
  - `location`: `{x: int, y: int, z: int}`
  - `all_waypoints`: List of all waypoint names at this location

## Behavior & Performance

- Stores waypoint in SpatialMap cell at specified coordinates
- Creates cell if it doesn't exist
- Multiple waypoints can be stored at the same location
- Waypoints persist in SpatialMap and can be queried via cell data
- Auto-saves SpatialMap after update
- If coordinates not provided, automatically queries mc-status for current position

## Guidelines

- Use meaningful waypoint names (e.g., "Base_Camp", "Pit_Exit_1")
- Waypoints enable spatial reasoning and navigation
- Waypoints are stored in SpatialMap cells and persist across sessions
- Omit `dx, dy, dz` to mark current position, or specify relative offsets (see coordinate system in jill-minecraft.yaml)

## Usage Examples

Create waypoint at current position:
```json
{"type":"mc-waypoint","name":"Base_Camp","out":"$result"}
```

Create waypoint at relative position:
```json
{"type":"mc-waypoint","name":"Pit_Exit_1","dx":2,"dy":-6,"dz":3,"out":"$result"}
```

Overview

This skill labels a world coordinate with a named waypoint to support navigation and spatial reasoning. It persists named locations in a SpatialMap so the agent can recall, compare, and plan around key positions. Use it to mark current or offset positions for later queries and routing.

How this skill works

You provide a waypoint name and optional dx, dy, dz offsets relative to the agent; if offsets are omitted the skill queries the agent's current position. The skill stores the waypoint in a SpatialMap cell for the computed world coordinates, creating the cell if needed and allowing multiple names per cell. It returns a human-readable success message and a machine-readable object with the waypoint name, absolute location, and list of waypoints at that cell. The SpatialMap is auto-saved so waypoints persist across sessions.

When to use it

Mark your base, resource nodes, or points of interest for later navigation
Annotate a safe exit or entrance while exploring caves or builds
Save locations to enable path planning or distance comparisons
Record dynamic locations (e.g., recent loot, portal) for multi-step tasks
Create consistent labels to share or reference in follow-up actions

Best practices

Use concise, descriptive names (e.g., Base_Camp, Pit_Exit_1) to avoid ambiguity
Omit dx/dy/dz to label your current location; use offsets to mark nearby spots
Re-use existing names only when you intend to update that location
Group related waypoints with a consistent naming convention for easier queries
Rely on the returned location data for programmatic routing rather than parsing text

Example use cases

Create a waypoint 'Base_Camp' at your current coordinates for return navigation
Label the top of a ravine using dx/dy/dz offsets from your standing position
Mark multiple exit points from an underground complex to plan escape routes
Store named resource nodes (e.g., Iron_Node_3) to coordinate mining runs
Add temporary waypoints during a multi-stage build or exploration task

FAQ

What happens if I create multiple waypoints at the same coordinates?

The SpatialMap cell stores multiple waypoint names; the response lists all names at that location.

Do waypoints persist between sessions?

Yes. The skill auto-saves the SpatialMap after updates so waypoints remain available later.

How do I mark my exact current position?

Omit dx, dy, dz and the skill will query the agent's current position and create the waypoint there.