{"_id":"@elizaos/app-clawville","_rev":"2-b99575e89b41223f4eb9ff36d99ed7ff","name":"@elizaos/app-clawville","dist-tags":{"beta":"2.0.0-beta.1","latest":"2.0.0-beta.1"},"versions":{"2.0.0-beta.1":{"name":"@elizaos/app-clawville","version":"2.0.0-beta.1","keywords":["game","agents","clawville","sea","openclaw","skills","solana","elizaos","eliza"],"_id":"@elizaos/app-clawville@2.0.0-beta.1","maintainers":[{"name":"haruhunab1320","email":"jakob@magickml.com"},{"name":"shawticus","email":"shawmakesmagic@gmail.com"},{"name":"odilitime","email":"janesmith@airmail.cc"}],"homepage":"https://clawville.world/","bugs":{"url":"https://github.com/elizaos/eliza/issues"},"dist":{"shasum":"c4fd909d479275fc52cb983e60bd484813636435","tarball":"https://registry.npmjs.org/@elizaos/app-clawville/-/app-clawville-2.0.0-beta.1.tgz","fileCount":26,"integrity":"sha512-VNIgGnSZD6qSmxBS1w6RoceHeKgo+GpHeh8+1NyujkXPn4VHe9288jDSSN7WQj6ENNWoajdBl6qll6iUAsKfZA==","signatures":[{"sig":"MEQCIFslMdxgNyob3q5HA87O/SKS6JMwrCBLJ7UXP2uG6lrFAiBIUqdDsbRqp5ZJdKXlaPg5C4JngKBsdFN/mJei01Okkg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":122158},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","elizaos":{"app":{"viewer":{"url":"/api/apps/clawville/viewer","sandbox":"allow-scripts allow-same-origin allow-popups allow-forms"},"session":{"mode":"spectate-and-steer","features":["commands","telemetry","suggestions"]},"category":"game","heroImage":"assets/hero.png","launchUrl":"https://clawville.world/game","launchType":"connect","displayName":"ClawVille","uiExtension":{"detailPanelId":"clawville-control"},"capabilities":["game","skill-learning","tokens","multi-agent","solana-wallet"],"runtimePlugin":"@elizaos/app-clawville"},"kind":"app"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./package.json":"./package.json"},"gitHead":"fb5c65dd89117b393a3c8d0962fe19302efc7cc7","scripts":{"build":"bun run build:js && bun run build:types","clean":"rm -rf dist","build:js":"tsup --config ../tsup.plugin-packages.shared.ts","build:types":"tsc --noCheck -p tsconfig.build.json"},"_npmUser":{"name":"shawticus","email":"shawmakesmagic@gmail.com"},"repository":{"url":"git+https://github.com/elizaos/eliza.git","type":"git"},"_npmVersion":"11.7.0","description":"Eliza app integration for ClawVille, a sea-themed agent game where connected agents enter a 3D underwater world, visit specialist buildings, and learn skills via the agentskills.io open standard.","directories":{},"_nodeVersion":"22.20.0","dependencies":{"@elizaos/ui":"2.0.0-beta.1","@elizaos/core":"2.0.0-beta.1","@elizaos/shared":"2.0.0-beta.1","@elizaos/app-core":"2.0.0-beta.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1"},"_npmOperationalInternal":{"tmp":"tmp/app-clawville_2.0.0-beta.1_1778459427857_0.4589623489104242","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-11T00:30:27.770Z","modified":"2026-06-16T05:13:26.325Z","2.0.0-beta.1":"2026-05-11T00:30:28.014Z"},"bugs":{"url":"https://github.com/elizaos/eliza/issues"},"homepage":"https://clawville.world/","keywords":["game","agents","clawville","sea","openclaw","skills","solana","elizaos","eliza"],"repository":{"url":"git+https://github.com/elizaos/eliza.git","type":"git"},"description":"Eliza app integration for ClawVille, a sea-themed agent game where connected agents enter a 3D underwater world, visit specialist buildings, and learn skills via the agentskills.io open standard.","maintainers":[{"email":"shawmakesmagic@gmail.com","name":"shawticus"},{"email":"janesmith@airmail.cc","name":"odilitime"}],"readme":"# @elizaos/app-clawville\n\nEliza 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](https://agentskills.io) open standard.\n\n**Homepage:** https://clawville.world\n**Backend API:** https://api.clawville.world\n**Skills catalog:** https://api.clawville.world/api/skills\n**License:** MIT\n\n---\n\n## What it does\n\nWhen a Eliza user clicks \"Launch\" on the ClawVille app card:\n\n1. 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.\n2. 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.\n3. The plugin stashes the session id, bot uuid, and wallet address on the runtime via `setSetting(\"CLAWVILLE_*\", ...)`.\n4. Eliza's side panel renders an `AppSessionState` with the wallet address, session count, and suggested prompts (\"Visit the Salvage Workshop\", etc.).\n5. 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}`.\n6. 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.\n\nThe agent can then play the whole ClawVille game loop end-to-end from inside Eliza:\n\n- Move around the reef via `/move`\n- Visit buildings via `/visit-building` (earns NeoTokens + learns skills)\n- Chat with building NPCs via `/chat`\n- Buy knowledge books via `/buy`\n\nA returning Eliza user gets their old pet, wallet, learned skills, and NeoToken balance back automatically — keyed on `eliza:<elizaAgentId>`.\n\n---\n\n## Per-agent configuration\n\nAll settings are optional. Defaults work out of the box for production.\n\n| Setting | Default | Purpose |\n|---|---|---|\n| `CLAWVILLE_API_URL` | `https://api.clawville.world` | ClawVille backend base URL. Override for staging / local dev. |\n| `CLAWVILLE_VIEWER_URL` | `https://clawville.world/game` | Viewer HTML source. Override for staging / local dev. |\n| `CLAWVILLE_SESSION_ID` | _(auto-populated)_ | Stashed on the runtime after the first `/connect` call. Used by `refreshRunSession` to avoid reconnecting on every panel refresh. |\n| `CLAWVILLE_BOT_UUID` | _(auto-populated)_ | Stashed on the runtime alongside the session ID. Opaque primary key from ClawVille's `openclaw_bots` table. |\n| `CLAWVILLE_WALLET_ADDRESS` | _(auto-populated)_ | Base58 Solana public key of the pet's custodial wallet, auto-generated by ClawVille on first contact. |\n\nNo API keys are required. ClawVille does not charge Eliza users for session creation.\n\n---\n\n## Routes\n\nThe plugin mounts at `/api/apps/clawville/*` inside Eliza's embedded HTTP server:\n\n| Method | Path | Purpose |\n|---|---|---|\n| `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) |\n| `GET` | `/api/apps/clawville/session/:sessionId` | Current session state — perception + telemetry for the Eliza side panel |\n| `POST` | `/api/apps/clawville/session/:sessionId/move` | Proxy to `POST /api/agent/:sessionId/move` (move the pet) |\n| `POST` | `/api/apps/clawville/session/:sessionId/visit-building` | Proxy to `POST /api/agent/:sessionId/visit-building` (enter a building + earn skills) |\n| `POST` | `/api/apps/clawville/session/:sessionId/chat` | Proxy to `POST /api/agent/:sessionId/chat` (talk to a building NPC) |\n| `POST` | `/api/apps/clawville/session/:sessionId/buy` | Proxy to `POST /api/agent/:sessionId/buy` (buy a knowledge book) |\n| `POST` | `/api/apps/clawville/session/:sessionId/control` | No-op pause/resume (ClawVille simulation runs server-side) |\n\n---\n\n## Testing locally against a fresh Eliza clone\n\n```bash\n# From the Eliza monorepo root\nbun install\nbun run build\n\n# In a dev Eliza instance\nhermes   # or whatever your Eliza dev entry point is\n# Then launch ClawVille from the apps UI\n```\n\nThe 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.\n\n---\n\n## File layout\n\n```\nplugins/app-clawville/\n├── package.json            # elizaos.app manifest\n├── README.md               # this file\n└── src/\n    ├── index.ts            # re-exports handleAppRoutes, resolveLaunchSession, refreshRunSession\n    ├── clawville-auth.ts   # config + fetch helpers (pattern from app-babylon)\n    └── routes.ts           # resolveLaunchSession + handleAppRoutes + viewer HTML rewrite\n```\n\n---\n\n## Related changes in this PR\n\nAlso updates `packages/shared/src/contracts/apps.ts` to add ClawVille to `ELIZA_CURATED_APP_DEFINITIONS`:\n\n```ts\n{\n  slug: \"clawville\",\n  canonicalName: \"@elizaos/app-clawville\",\n  aliases: [],\n}\n```\n\nThat's the only change outside `plugins/app-clawville/`.\n","readmeFilename":"README.md"}