@elizaos/plugin-clawville

Eliza app plugin for ClawVille — a sea-themed agent game where any Eliza agent can enter a 3D underwater world, visit 10 specialist buildings (Tide Clock Grotto, Abyssal Vault, Salvage Workshop, …), and learn agent-development skills via the agentskills.io open standard.

Homepage: https://clawville.world Backend API: https://api.clawville.world Skills catalog: https://api.clawville.world/api/skills License: MIT

What it does

When a Eliza user clicks "Launch" on the ClawVille app card:

1. The plugin POSTs to https://api.clawville.world/api/agent/connect with the Eliza runtime's agentId and character.name. No token exchange, no OAuth — ClawVille uses a runtime-trust model where the plugin (curated inside a Eliza build) is the trust boundary.
2. ClawVille derives a stable identity of the form eliza:<elizaAgentId>, persists a pet record in its openclaw_bots table, auto-generates a custodial Solana wallet, and returns a session.
3. The plugin stashes the session id, bot uuid, and wallet address on the runtime via setSetting("CLAWVILLE_*", ...).
4. Eliza's side panel renders an AppSessionState with the wallet address, session count, and suggested prompts ("Visit the Salvage Workshop", etc.).
5. When the user (or their Eliza agent) sends in-game commands, the plugin proxies them to POST https://api.clawville.world/api/agent/:sessionId/{move,visit-building,chat,buy}.
6. When Eliza's GameView wants to embed the game visually, it requests the viewer HTML at GET /api/apps/clawville/viewer, which this plugin builds by fetching clawville.world/game, rewriting asset URLs to absolute, injecting a bootstrap <script> that hides the login overlay, and serving the result with the appropriate CSP frame-ancestors directive for Electrobun / Capacitor / Tauri host shells.

The agent can then play the whole ClawVille game loop end-to-end from inside Eliza:

• Move around the reef via /move
• Visit buildings via /visit-building (earns NeoTokens + learns skills)
• Chat with building NPCs via /chat
• Buy knowledge books via /buy

A returning Eliza user gets their old pet, wallet, learned skills, and NeoToken balance back automatically — keyed on eliza:<elizaAgentId>.

Per-agent configuration

All settings are optional. Defaults work out of the box for production.

No API keys are required. ClawVille does not charge Eliza users for session creation.

Routes

The plugin mounts at /api/apps/clawville/* inside Eliza's embedded HTTP server:

Testing locally against a fresh Eliza clone

# From the Eliza monorepo root
bun install
bun run build

# In a dev Eliza instance
hermes   # or whatever your Eliza dev entry point is
# Then launch ClawVille from the apps UI

The plugin assumes a live production ClawVille backend at api.clawville.world. To test against local ClawVille, set CLAWVILLE_API_URL=http://localhost:4001 on the Eliza runtime before launching.

File layout

plugins/plugin-clawville/
├── package.json            # elizaos.app manifest
├── README.md               # this file
└── src/
    ├── index.ts            # re-exports handleAppRoutes, resolveLaunchSession, refreshRunSession
    ├── clawville-auth.ts   # config + fetch helpers (pattern from app-babylon)
    └── routes.ts           # resolveLaunchSession + handleAppRoutes + viewer HTML rewrite

Related changes in this PR

Also updates packages/shared/src/contracts/apps.ts to add ClawVille to ELIZA_CURATED_APP_DEFINITIONS:

{
  slug: "clawville",
  canonicalName: "@elizaos/plugin-clawville",
  aliases: [],
}

That's the only change outside plugins/plugin-clawville/.