Blockworld

YouTube Video: https://youtu.be/EHHd7kv7y3I

A voxel world for an AI agent to build in.

• An MCP server — tools for placing blocks.
• A viewer — renders the world as line art, live, block by block as the agent works.
• Skills — markdown that teaches an agent what a fairytale castle or a dragon looks like, and how to build one here.

The agent brings the knowledge. The server gives it hands. The skills give it the brief.

<img src="./image.jpg">

---

Run it

npm install
npm run viewer        # → http://localhost:5173/viewer/

Opens with a mock castle so you can see it working straight away. Add ?live to suppress it.

Then point an agent at the MCP server:

{
  "mcpServers": {
    "blockworld": {
      "command": "node",
      "args": ["/absolute/path/to/blockworld/server.js"]
    }
  }
}

It broadcasts on a WebSocket, so the viewer shows each block as it lands.

> build me a castle
> build me a dragon

---

Controls

drag / scroll / right-drag	orbit, zoom, pan
F	reframe
R	auto-rotate
G / E	grid, edges
1–4	three-quarter, front, side, plan

2 is the silhouette view — the best angle for judging what a build actually reads as.

---

Tools

world_info	the grid scale — call first
list_materials	100 materials
place_box	walls, floors, rooms
place_cylinder	towers, columns
place_cone	spires, caps, horns
place_sphere	domes, skulls, orbs
place_tube	curved forms — necks, tails, bodies
mirror	build one half, mirror it
remove_box	carve gates, windows
place_block	detail only
clear · describe_world	reset, inspect

Everything is cubes. place_sphere and place_tube don't render spheres or tubes — they rasterize a shape into cubes server-side. The point is tool-call economy: the agent describes a form (a path, a radius, a taper) instead of computing five thousand coordinates.

---

Skills

.claude/skills/
  blockworld/   scale, materials, primitives, build order   ← read first
  castle/       fairytale: slender spires, steep caps, gold
  dragon/       S-curve spine, membrane wings, taper

Plain markdown, no vendor syntax. Claude Code and Grok both discover .claude/skills/ automatically. Grok also reads .grok/skills/, and some agents use .agents/skills/ — the path doesn't matter to the content, so rename freely. Any other agent: point it at the files directly.

---

The one dial

config.js:

export const BLOCK_SIZE = 1.0;   // metres per block

Everything follows — viewer scale, server readouts, and the agent's own sense of how big to build. It doesn't read the block size from markdown; it calls world_info, which derives reference dimensions from the config at runtime:

One block is 50 cm.
  castle wall     18 tall
  castle tower    52 tall
  large dragon   100 long

The skills are written in ratios — wingspan = 1.5× body length, towers 3× the wall — never metres. So halving BLOCK_SIZE gets you a dragon that's still 50m long but made of 8× the cubes. No skill edits.

Layout

config.js            the one dial
palette.js           100 materials, shared
server.js            MCP over stdio + WebSocket :8080
viewer/index.html    Three.js from CDN, no build step
.claude/skills/      blockworld · castle · dragon