@elizaos/app-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.

| Setting | Default | Purpose | |---|---|---| | CLAWVILLE_API_URL | https://api.clawville.world | ClawVille backend base URL. Override for staging / local dev. | | CLAWVILLE_VIEWER_URL | https://clawville.world/game | Viewer HTML source. Override for staging / local dev. | | CLAWVILLE_SESSION_ID | (auto-populated) | Stashed on the runtime after the first /connect call. Used by refreshRunSession to avoid reconnecting on every panel refresh. | | CLAWVILLE_BOT_UUID | (auto-populated) | Stashed on the runtime alongside the session ID. Opaque primary key from ClawVille's openclaw_bots table. | | CLAWVILLE_WALLET_ADDRESS | (auto-populated) | Base58 Solana public key of the pet's custodial wallet, auto-generated by ClawVille on first contact. |

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:

| Method | Path | Purpose | |---|---|---| | GET | /api/apps/clawville/viewer | Serves the embedded game HTML (fetches clawville.world/game, rewrites asset URLs, injects embed-mode bootstrap script, applies frame-ancestors CSP) | | GET | /api/apps/clawville/session/:sessionId | Current session state — perception + telemetry for the Eliza side panel | | POST | /api/apps/clawville/session/:sessionId/move | Proxy to POST /api/agent/:sessionId/move (move the pet) | | POST | /api/apps/clawville/session/:sessionId/visit-building | Proxy to POST /api/agent/:sessionId/visit-building (enter a building + earn skills) | | POST | /api/apps/clawville/session/:sessionId/chat | Proxy to POST /api/agent/:sessionId/chat (talk to a building NPC) | | POST | /api/apps/clawville/session/:sessionId/buy | Proxy to POST /api/agent/:sessionId/buy (buy a knowledge book) | | POST | /api/apps/clawville/session/:sessionId/control | No-op pause/resume (ClawVille simulation runs server-side) |

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/app-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/app-clawville",
  aliases: [],
}

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