Tools
Agentshire
By OpenClaw plugin that visualizes AI agents as 3D NPCs in a game town — with social simulation, a map editor, and a character workshop.
Install
npm install &&Configuration Example
{
"plugins": {
"entries": {
"agentshire": {
"enabled": true,
"config": {
"wsPort": 55211,
"townPort": 55210,
"autoLaunch": true
}
}
}
}
}README
# Agentshire
English | [中文](README.zh-CN.md)
> **Agentshire — Let your OpenClaw agents live in a game town you built yourself， not a dashboard.**
Agentshire is an [OpenClaw](https://github.com/openclaw/openclaw) plugin that turns AI agents into living NPCs inside a 3D town you can watch, chat with, and shape yourself. It combines a living simulation layer with UGC tools: weather, day/night cycles, social NPCs, a map editor, and a character workshop.
**[Vision](VISION.md)** | **[Roadmap](ROADMAP.md)**
> **⚠️ Compatibility Notice**
>
> | OpenClaw Version | Status | Notes |
> |---|---|---|
> | **2026.3.13** | ✅ Recommended | Fully tested and supported |
> | 2026.3.7 – 3.12 | ⚠️ May work | Not actively tested |
> | 2026.4.x+ | ❌ Not supported yet | Channel plugin initialization regression — [tracking issue](https://github.com/openclaw/openclaw/issues) |
>
> See [Troubleshooting](#troubleshooting) for version-specific issues.
---
## See It in Action
> **📺 [Watch the full demo on YouTube](https://www.youtube.com/watch?v=R6YXvkkwo9I)**
**A town, not a dashboard.**
https://github.com/user-attachments/assets/c888d2ef-dcba-4caa-b0af-9b5f3e3b1365
**Build your characters — pick a model, give them a soul, watch them come alive.**
https://github.com/user-attachments/assets/b9697432-b3ba-4e23-85fe-4c0b5c35a1b9
**Build your town — drag, drop, preview.**
https://github.com/user-attachments/assets/3328aa6c-3432-4f71-abfd-91aea4db15df
**Every citizen has a mind of their own.**
https://github.com/user-attachments/assets/720a63fc-863c-483c-bfdf-5e07e82c6f0e
**Give them a mission. Watch them rally.**
https://github.com/user-attachments/assets/1983f60b-aaf6-4adc-b46c-5612e4ba4c83
**Work too long? Banwei Boss appears. Pop it.**
https://github.com/user-attachments/assets/9be946e0-9ecf-42de-b793-a5d7ebe55612
**Mission complete. Fireworks. Playable game delivered.**
https://github.com/user-attachments/assets/fa6563ae-e78b-49b1-ae7b-8a8a96738341
---
## Features
### Dual-Mode Interface
- **Town Mode** — Low-poly 3D town where you watch NPCs live, work, collaborate, and celebrate in real time
- **Chat Mode** — IM-style chat interface with an agent list (steward + citizens, online status), message history, multimodal support (text/image), and commands (`/new` `/help` `/stop`)
- **Top Navigation** — One-click switch between Town and Chat, with a quick menu (Citizen Workshop / Town Editor / Skill Store / Settings)
### Core
- **Agent = NPC** — Every sub-agent automatically becomes a 3D citizen with a name, appearance, and personality
- **Cinematic Workflow** — Summon → Rally → Assign → Enter Office → Code → Celebrate → Return to Town, fully choreographed with animations
- **Real-Time Dialog Bubbles** — AI responses appear above NPC heads with a typewriter effect, streaming updates, and pagination
- **Multi-Agent Collaboration** — The steward automatically decomposes tasks into parallel steps with file boundary validation
- **Zero Configuration** — Install the plugin, start the Gateway, and the town runs automatically
### Town Life
- **Day/Night Cycle** — 24-hour clock (6 periods), real-time lighting changes, automatic street/window lights
- **12 Weather Types** — Clear / cloudy / fog / drizzle / rain / storm / snow / blizzard / sandstorm / aurora… daily random theme with smooth transitions
- **Procedural Ambient Sound** — Rain, wind, birdsong, crickets, traffic, thunder — all synthesized in real time via Web Audio API, zero audio files
- **4-Track BGM** — Day / dusk / night / work tracks, auto-switching by weather, time period, and scene with 3.5s crossfade
- **NPC Daily Behavior (Dual Mode)** — Algorithm-driven by default: state machine + 5 behavior templates + 400+ preset dialog lines, zero LLM cost. Enable Soul Mode to switch to AI-driven: AgentBrain 3-tier decisions (L1 daily plan / L2 tactical / L3 dialogue) + deep multi-turn LLM conversations + relationship graph + daily narrative summaries
- **Citizen Chat** — Click any citizen NPC to start a conversation, routed to that citizen's independent Agent session
- **Banwei Buster Mini-Game** — NPCs generate "banwei orbs" while working; click to pop them! Includes combo system, boss battles, and NPC stress mechanics
### UGC Tools
- **Citizen Workshop** — Create and configure citizen characters: select/upload 3D models, edit soul personality (AI generation supported), configure animation mapping (8 slots), publish as independent Agents
- **Town Editor** — Visual drag-and-drop map editing: place buildings/roads/props/lights, with grouping, alignment, undo, and JSON export (runtime integration in progress)
- **Editor Preview** — One-click game-level preview window (WASD controls + full day/night + weather + vehicle animations + audio)
- **Soul System** — Each NPC has a Markdown personality file defining character traits, speaking style, expertise, and work approach
### Interaction & Visuals
- **Interactive 3D** — Click NPCs to view status cards (avatar / persona / work logs / thinking stream / TODO), drag to pan, scroll to zoom
- **3 Scene Types** — Town (daily life) / Office (work) / Showroom (in development), with fade transitions and NPC migration
- **Rich VFX** — Summon shockwave, completion fireworks, error lightning, persona-transform magic circle, thinking halo, search radar, confetti…
- **10-Workstation Office** — Each workstation has its own monitor (real-time code animation), full NPC enter/work/leave choreography
- **Deliverable Preview** — After project completion, deliverable cards pop up with image lightbox, video, audio preview and download; games/websites launch directly in iframe
- **AI Tool Control** — Agents can control the town via tools (broadcast messages, spawn NPCs, trigger effects, set time/weather)
- **Reconnection** — WebSocket auto-reconnect with exponential backoff and work state recovery
---
## Requirements
- [OpenClaw](https://github.com/openclaw/openclaw) **2026.3.13** (recommended)
- Node.js >= 18
---
## Quick Install
> **⚠️ The plugin has not been published to npm yet.** `openclaw plugins install agentshire` is not available. Use the **link install** method below.
### Link Install
```bash
# 1. Clone the repository
git clone https://github.com/Agentshire/Agentshire.git
cd Agentshire
# 2. Build the frontend
cd town-frontend && npm install && npm run build && cd ..
# 3. Link-install into OpenClaw
openclaw plugins install --link .
```
### What the plugin auto-configures on first start
1. Creates the steward workspace at `~/.openclaw/workspace-town-steward/`
2. Registers the `town-steward` Agent in `openclaw.json`
3. Adds a routing rule to direct town channel messages to the steward
4. Sets `subagents.runTimeoutSeconds: 600` — 10-minute timeout to prevent premature subagent termination
> **Important**: Do **not** add a `tools` section to `openclaw.json`. The plugin registers its own tools via `api.registerTool()`. A manual `tools.allow` list will override plugin-registered tools, making them invisible to the agent.
### Update
```bash
cd Agentshire && git pull
cd town-frontend && npm install && npm run build && cd ..
openclaw plugins install --link .
```
Then restart the Gateway.
---
## Usage
1. Complete the [Quick Install](#quick-install) steps
2. Start (or restart) the OpenClaw Gateway:
```bash
openclaw gateway
```
3. The town opens automatically in your browser
4. Chat in the browser — all Agent activity is automatically mapped to the town
> **Tip**: If the browser didn't open automatically, visit:
> `http://localhost:55210?ws=ws://localhost:55211`
### Citizen Workshop
Visit `http://localhost:55210/citizen-editor.html` to create and configure your NPC team.
### Town Editor
Visit `http://localhost:55210/editor.html` to open the visual map editor.
### Configuration (Optional)
Customize ports and behavior in `~/.openclaw/openclaw.json`:
```json
{
"plugins": {
"entries": {
"agentshire": {
"enabled": true,
"config": {
"wsPort": 55211,
"townPort": 55210,
"autoLaunch": true
}
}
}
}
}
```
| Option | Default | Description |
|--------|---------|-------------|
| `wsPort` | 55211 | WebSocket port (real-time plugin ↔ frontend communication) |
| `townPort` | 55210 | HTTP port (frontend static files + editor API) |
| `autoLaunch` | true | Auto-open town in browser on startup |
### AI Tools
| Tool | Description |
|------|-------------|
| `town_announce` | Broadcast a message in the town |
| `town_spawn_npc` | Spawn a new NPC |
| `town_effect` | Trigger visual effects (celebration / fireworks / glow, etc.) |
| `town_set_time` | Control the game clock |
| `town_set_weather` | Control weather (12 types available) |
| `town_status` | View current town status |
| `register_project` | Register a simple project (single-agent or steward-only) |
| `create_project` | Create a project directory for multi-agent work |
| `create_task` | Create a task directory for single-agent delegation |
| `create_plan` | Create a collaboration plan (parallel steps, requires `create_project` or `create_task` first) |
| `next_step` | Query plan progress and get next step instructions |
| `mission_complete` | Unified completion handler — auto-routes to celebration or partial delivery based on remaining work |
---
## Soul System
Every NPC has an independent **soul file** (Markdown) that defines personality, speaking style, expertise, and work approach.
Format: a Markdown file starting with `# Character Name`, optionally containing metadata (model ID, gender, role), core persona, detailed personality settings, and dialog examples. The content is injected as the Agent's system prompt.
**Search priority** (later overrides earlier):
1. `plugin-builtin/town-souls/` — Preset souls (8 citizens + steward)
2. `cwd/town-souls/` — Project-level souls
3. `~/.openclaw/town-souls/` — User custom souls
4. `town-data/souls/` — Souls published from Citizen Workshop
You
... (truncated)
tools
Comments
Sign in to leave a comment