home / skills / bdambrosio / cognitive_workbench / mc-local-grid-visualize

mc-local-grid-visualize skill

safe

/src/world-tools/minecraft/mc-local-grid-visualize

This skill generates an interactive 3D HTML visualization of the session-local occupancy grid and opens it in the browser.

npx playbooks add skill bdambrosio/cognitive_workbench --skill mc-local-grid-visualize

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-local-grid-visualize
type: python
description: "Generates interactive 3D HTML visualization of the session-local occupancy grid. Opens in browser."
---

# Minecraft Local Grid Visualization Tool

Generates an interactive 3D HTML visualization of the session-local rolling occupancy grid using Three.js. Displays voxels as colored cubes with rotation, zoom, and pan controls.

## Purpose

Visualize the transient 3D occupancy grid for debugging navigation, collision recovery, and planning decisions. Shows what the agent "knows" about nearby blocks.

## Input

- `output_file`: Optional output file path (default: `/tmp/local_grid_viz.html`)

## Output

Returns uniform_return format with:
- `value`: Summary text with file path and voxel count
- `data`: `{success, file_path, cell_count, center, radius}`

Also opens generated HTML file in default browser.

## Visualization Features

Interactive 3D viewer:
- **Rotate**: Left-click and drag
- **Pan**: Right-click and drag  
- **Zoom**: Mouse wheel
- **Hover**: Shows block name and position

Visual elements:
- **Voxels**: Colored cubes (block-name → color mapping)
- **Agent center**: Red sphere marker
- **Radius boundary**: Green wireframe cube (radius 10)
- **Grid helper**: Reference grid at agent Y-level

## Behavior & Performance

- Reads grid directly from `executor.get_world_state("local_grid")`
- Generates self-contained HTML file (Three.js via CDN)
- Auto-opens in default browser
- Static snapshot (refresh browser and re-run tool for updates)

## Guidelines

- Use after `mc-observe` / `mc-dig` / `mc-place` to see updated grid state
- Keep browser open and refresh page after re-running tool for latest snapshot
- Hover over voxels to see block names and coordinates
- Use zoom to inspect specific regions

## Usage Examples

Visualize current grid state:
```json
{"type":"mc-local-grid-visualize","out":"$viz"}
```

Specify output file:
```json
{"type":"mc-local-grid-visualize","output_file":"/tmp/my_grid.html","out":"$viz"}
```

Overview

This skill generates an interactive 3D HTML visualization of the session-local rolling occupancy grid and opens it in the default web browser. It renders voxels as colored cubes and includes controls for rotate, pan, and zoom so you can inspect what the agent perceives around itself. The tool produces a self-contained HTML snapshot that you can refresh after re-running to view updates.

How this skill works

The skill reads the current local occupancy grid from the agent runtime (executor.get_world_state("local_grid")). It converts each occupied cell into a colored voxel and writes a standalone HTML file using Three.js from a CDN. The generated file is automatically opened in the default browser and shows an agent center marker, a radius boundary, and interactive hover tooltips for block name and coordinates.

When to use it

After performing observations or actions (mc-observe, mc-dig, mc-place) to inspect the updated grid.
When debugging navigation, collision recovery, or path-planning decisions based on nearby blocks.
To verify what the agent currently 'sees' and confirm sensor/voxel mapping correctness.
When you need a quick visual snapshot of the agent's local environment without running long simulations.

Best practices

Run the tool immediately after modifying the world state and refresh the browser to compare snapshots.
Specify a custom output_file when saving multiple snapshots to avoid overwriting.
Use hover tooltips and zoom to identify specific blocks and coordinates for targeted debugging.
Keep the browser open while iterating; re-run the skill and refresh to view new snapshots.

Example use cases

Visualize the occupancy grid after a failed pathfinding attempt to see unexpected obstacles.
Confirm that newly placed or dug blocks are registered correctly in the local grid.
Share a static HTML snapshot with teammates for offline inspection and troubleshooting.

FAQ

Does the viewer update in real time?

No. The generated HTML is a static snapshot. Re-run the skill and refresh the browser to see updates.

Where is the file saved by default?

By default the HTML file is written to /tmp/local_grid_viz.html unless you specify output_file.