Turning AI Agents into Visible NPCs: Building a 3D Town Plugin for QClaw

Overview

Agentshire is an open‑source plugin that visualizes QClaw/OpenClaw AI agents as 3D NPCs in a small town. It enables real‑time observation, control and editing of agent behavior.

Installation

For QClaw (0.2.x) run:

install plugin https://github.com/Agentshire/Agentshire

For OpenClaw CLI (2026.3.13) run: openclaw plugins install agentshire No configuration files need to be edited; the plugin automatically creates a manager, registers the agent and sets up routing.

Features

Visible : event translation and real‑time tracking render agent actions as NPC animations and thought bubbles.

Controllable : a structured multi‑agent orchestration layer coordinates tasks, context and feedback.

Editable : JSON‑driven UGC lets users modify town layout, NPC personalities and assets without code changes.

Technical Architecture

QClaw / OpenClaw (10+ Hook callbacks)
    │ Hook events
    ▼
Plugin translation layer (Node.js)
    │ Hook → 26+ AgentEvent → WebSocket broadcast
    ▼
Bridge orchestration layer (browser)
    │ AgentEvent → 65 GameEvent → Phase state machine
    ▼  ↕ Intent + feedback
Frontend rendering layer (Three.js)
    │ NPC state machine, workflow animation, weather, day‑night cycle

Visibility

The plugin polls each agent’s JSONL session log every 300 ms, extracts thinking, tool_use, tool_result and text events and renders them as thought bubbles, tool animations or dialogue above the corresponding NPC.

Control

Multi‑agent collaboration follows a four‑step pipeline:

create_project → create_plan → next_step → mission_complete

. The bridge receives only high‑level intent signals; after the front‑end finishes its animation it sends a done signal, allowing the next phase to start. This “intent + feedback” model eliminates timing guesses and race conditions.

Editability

All town assets are defined in JSON files. Publishing a citizen-config.json atomically creates or updates the corresponding agent and synchronizes default town settings. The system supports four overlay levels: plugin‑built‑in → project → user custom → workshop publish, with later layers overriding earlier ones.

Workflow Batches

Batch 1 – Product Manager – requirements specification (SPEC.md)

Batch 2 – Architect + Designer – skeleton code, MODULES.md / DESIGN.md

Batch 3 – Developers – module implementations

Batch 4 – Integration testing – final verification and release

Future Directions

Close the loop: integrate the editor map with the runtime, support OpenClaw 4.x, improve multi‑agent delivery quality.

Make towns alive: persistent NPC memory, permanent agents, lifestyle simulation and growth systems.

Connect towns: cross‑town NPC visits, skill exchange, global events and federation protocols.

License

MIT license. Repository: https://github.com/Agentshire/Agentshire