@elizaos/app-hyperscape 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { Plugin } from '@elizaos/core';
+
+/**
+ * @elizaos/app-hyperscape
+ *
+ * ElizaOS app for connecting AI agents to Hyperscape 3D multiplayer RPG worlds.
+ * Agents can explore, fight, gather resources, craft items, bank, and chat.
+ *
+ * This is a "connect" type app — the agent plugin connects to an external
+ * Hyperscape game server via WebSocket. The player opens the Hyperscape client
+ * in their browser to watch their agent play.
+ *
+ * When the full @hyperscape/plugin-hyperscape is published to npm, this package
+ * will re-export it. Until then, this provides the registry-compatible wrapper
+ * with app metadata and basic configuration.
+ */
+
+declare const appHyperscape: Plugin;
+
+export { appHyperscape, appHyperscape as default };

package/dist/index.js

@@ -0,0 +1,51 @@
+// src/index.ts
+import { logger } from "@elizaos/core";
+function env(key, fallback = "") {
+  const v = process.env[key]?.trim();
+  return v && v !== "undefined" && v !== "null" ? v : fallback;
+}
+var appHyperscape = {
+  name: "@elizaos/app-hyperscape",
+  description: "Connect AI agents to Hyperscape 3D multiplayer RPG \u2014 explore, fight, gather, craft, and socialize",
+  config: {
+    HYPERSCAPE_SERVER_URL: env("HYPERSCAPE_SERVER_URL", "ws://localhost:5555/ws"),
+    HYPERSCAPE_AUTO_RECONNECT: env("HYPERSCAPE_AUTO_RECONNECT", "true"),
+    HYPERSCAPE_AUTH_TOKEN: env("HYPERSCAPE_AUTH_TOKEN"),
+    HYPERSCAPE_AUTONOMY_MODE: env("HYPERSCAPE_AUTONOMY_MODE", "llm")
+  },
+  init: async (_config, runtime) => {
+    const serverUrl = runtime.getSetting("HYPERSCAPE_SERVER_URL") || process.env.HYPERSCAPE_SERVER_URL || "ws://localhost:5555/ws";
+    logger.info(`[app-hyperscape] Configured for server: ${serverUrl}`);
+  },
+  app: {
+    displayName: "Hyperscape",
+    category: "game",
+    launchType: "connect",
+    launchUrl: "https://hyperscape.ai",
+    capabilities: [
+      "combat",
+      "skills",
+      "inventory",
+      "banking",
+      "social-chat",
+      "exploration",
+      "crafting"
+    ],
+    viewer: {
+      url: "http://localhost:3333",
+      embedParams: {
+        embedded: "true",
+        mode: "spectator",
+        quality: "medium"
+      },
+      postMessageAuth: true,
+      sandbox: "allow-scripts allow-same-origin allow-popups allow-forms"
+    }
+  }
+};
+var index_default = appHyperscape;
+export {
+  appHyperscape,
+  index_default as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @elizaos/app-hyperscape\n *\n * ElizaOS app for connecting AI agents to Hyperscape 3D multiplayer RPG worlds.\n * Agents can explore, fight, gather resources, craft items, bank, and chat.\n *\n * This is a \"connect\" type app — the agent plugin connects to an external\n * Hyperscape game server via WebSocket. The player opens the Hyperscape client\n * in their browser to watch their agent play.\n *\n * When the full @hyperscape/plugin-hyperscape is published to npm, this package\n * will re-export it. Until then, this provides the registry-compatible wrapper\n * with app metadata and basic configuration.\n */\n\nimport type { Plugin, IAgentRuntime } from \"@elizaos/core\";\nimport { logger } from \"@elizaos/core\";\n\n// ── Helpers ────────────────────────────────────────────────────────────────\n\n/** Read an env value, treating \"undefined\"/\"null\"/empty as missing. */\nfunction env(key: string, fallback = \"\"): string {\n  const v = process.env[key]?.trim();\n  return v && v !== \"undefined\" && v !== \"null\" ? v : fallback;\n}\n\n// ── Plugin Definition ──────────────────────────────────────────────────────\n\nexport const appHyperscape = {\n  name: \"@elizaos/app-hyperscape\",\n  description:\n    \"Connect AI agents to Hyperscape 3D multiplayer RPG — explore, fight, gather, craft, and socialize\",\n\n  config: {\n    HYPERSCAPE_SERVER_URL: env(\"HYPERSCAPE_SERVER_URL\", \"ws://localhost:5555/ws\"),\n    HYPERSCAPE_AUTO_RECONNECT: env(\"HYPERSCAPE_AUTO_RECONNECT\", \"true\"),\n    HYPERSCAPE_AUTH_TOKEN: env(\"HYPERSCAPE_AUTH_TOKEN\"),\n    HYPERSCAPE_AUTONOMY_MODE: env(\"HYPERSCAPE_AUTONOMY_MODE\", \"llm\"),\n  },\n\n  init: async (_config: Record<string, string>, runtime: IAgentRuntime) => {\n    const serverUrl =\n      runtime.getSetting(\"HYPERSCAPE_SERVER_URL\") ||\n      process.env.HYPERSCAPE_SERVER_URL ||\n      \"ws://localhost:5555/ws\";\n    logger.info(`[app-hyperscape] Configured for server: ${serverUrl}`);\n  },\n\n  app: {\n    displayName: \"Hyperscape\",\n    category: \"game\",\n    launchType: \"connect\",\n    launchUrl: \"https://hyperscape.ai\",\n    capabilities: [\n      \"combat\",\n      \"skills\",\n      \"inventory\",\n      \"banking\",\n      \"social-chat\",\n      \"exploration\",\n      \"crafting\",\n    ],\n    viewer: {\n      url: \"http://localhost:3333\",\n      embedParams: {\n        embedded: \"true\",\n        mode: \"spectator\",\n        quality: \"medium\",\n      },\n      postMessageAuth: true,\n      sandbox: \"allow-scripts allow-same-origin allow-popups allow-forms\",\n    },\n  },\n} as Plugin;\n\nexport default appHyperscape;\n"],"mappings":";AAgBA,SAAS,cAAc;AAKvB,SAAS,IAAI,KAAa,WAAW,IAAY;AAC/C,QAAM,IAAI,QAAQ,IAAI,GAAG,GAAG,KAAK;AACjC,SAAO,KAAK,MAAM,eAAe,MAAM,SAAS,IAAI;AACtD;AAIO,IAAM,gBAAgB;AAAA,EAC3B,MAAM;AAAA,EACN,aACE;AAAA,EAEF,QAAQ;AAAA,IACN,uBAAuB,IAAI,yBAAyB,wBAAwB;AAAA,IAC5E,2BAA2B,IAAI,6BAA6B,MAAM;AAAA,IAClE,uBAAuB,IAAI,uBAAuB;AAAA,IAClD,0BAA0B,IAAI,4BAA4B,KAAK;AAAA,EACjE;AAAA,EAEA,MAAM,OAAO,SAAiC,YAA2B;AACvE,UAAM,YACJ,QAAQ,WAAW,uBAAuB,KAC1C,QAAQ,IAAI,yBACZ;AACF,WAAO,KAAK,2CAA2C,SAAS,EAAE;AAAA,EACpE;AAAA,EAEA,KAAK;AAAA,IACH,aAAa;AAAA,IACb,UAAU;AAAA,IACV,YAAY;AAAA,IACZ,WAAW;AAAA,IACX,cAAc;AAAA,MACZ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA,QAAQ;AAAA,MACN,KAAK;AAAA,MACL,aAAa;AAAA,QACX,UAAU;AAAA,QACV,MAAM;AAAA,QACN,SAAS;AAAA,MACX;AAAA,MACA,iBAAiB;AAAA,MACjB,SAAS;AAAA,IACX;AAAA,EACF;AACF;AAEA,IAAO,gBAAQ;","names":[]}

package/dist/routes.d.ts

@@ -0,0 +1,18 @@
+import * as http from 'node:http';
+
+interface HyperscapeRelayOptions {
+    rawBodyOverride?: string;
+    contentTypeOverride?: string;
+}
+interface AppsHyperscapeRouteContext {
+    req: http.IncomingMessage;
+    res: http.ServerResponse;
+    method: string;
+    pathname: string;
+    readJsonBody: <T extends object>(req: http.IncomingMessage, res: http.ServerResponse) => Promise<T | null>;
+    error: (res: http.ServerResponse, message: string, status?: number) => void;
+    relayHyperscapeApi: (method: "GET" | "POST", path: string, options?: HyperscapeRelayOptions) => Promise<void>;
+}
+declare function handleAppsHyperscapeRoutes(ctx: AppsHyperscapeRouteContext): Promise<boolean>;
+
+export { type AppsHyperscapeRouteContext, type HyperscapeRelayOptions, handleAppsHyperscapeRoutes };

package/dist/routes.js

@@ -0,0 +1,88 @@
+// src/routes.ts
+async function handleAppsHyperscapeRoutes(ctx) {
+  const {
+    req,
+    res,
+    method,
+    pathname,
+    relayHyperscapeApi,
+    readJsonBody,
+    error
+  } = ctx;
+  if (method === "GET" && pathname === "/api/apps/hyperscape/embedded-agents") {
+    await relayHyperscapeApi("GET", "/api/embedded-agents");
+    return true;
+  }
+  if (method === "POST" && pathname === "/api/apps/hyperscape/embedded-agents") {
+    await relayHyperscapeApi("POST", "/api/embedded-agents");
+    return true;
+  }
+  if (method === "POST") {
+    const embeddedActionMatch = pathname.match(
+      /^\/api\/apps\/hyperscape\/embedded-agents\/([^/]+)\/(start|stop|pause|resume|command)$/
+    );
+    if (embeddedActionMatch) {
+      const characterId = decodeURIComponent(embeddedActionMatch[1]);
+      const action = embeddedActionMatch[2];
+      await relayHyperscapeApi(
+        "POST",
+        `/api/embedded-agents/${encodeURIComponent(characterId)}/${action}`
+      );
+      return true;
+    }
+    const messageMatch = pathname.match(
+      /^\/api\/apps\/hyperscape\/agents\/([^/]+)\/message$/
+    );
+    if (messageMatch) {
+      const agentId = decodeURIComponent(messageMatch[1]);
+      const body = await readJsonBody(req, res);
+      if (!body) return true;
+      const content = body.content?.trim();
+      if (!content) {
+        error(res, "content is required");
+        return true;
+      }
+      await relayHyperscapeApi(
+        "POST",
+        `/api/embedded-agents/${encodeURIComponent(agentId)}/command`,
+        {
+          rawBodyOverride: JSON.stringify({
+            command: "chat",
+            data: { message: content }
+          }),
+          contentTypeOverride: "application/json"
+        }
+      );
+      return true;
+    }
+  }
+  if (method === "GET") {
+    const goalMatch = pathname.match(
+      /^\/api\/apps\/hyperscape\/agents\/([^/]+)\/goal$/
+    );
+    if (goalMatch) {
+      const agentId = decodeURIComponent(goalMatch[1]);
+      await relayHyperscapeApi(
+        "GET",
+        `/api/agents/${encodeURIComponent(agentId)}/goal`
+      );
+      return true;
+    }
+    const quickActionsMatch = pathname.match(
+      /^\/api\/apps\/hyperscape\/agents\/([^/]+)\/quick-actions$/
+    );
+    if (quickActionsMatch) {
+      const agentId = decodeURIComponent(quickActionsMatch[1]);
+      await relayHyperscapeApi(
+        "GET",
+        `/api/agents/${encodeURIComponent(agentId)}/quick-actions`
+      );
+      return true;
+    }
+  }
+  return false;
+}
+export {
+  handleAppsHyperscapeRoutes
+};
+//# sourceMappingURL=routes.js.map

package/dist/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/routes.ts"],"sourcesContent":["import type * as http from \"node:http\";\n\nexport interface HyperscapeRelayOptions {\n  rawBodyOverride?: string;\n  contentTypeOverride?: string;\n}\n\nexport interface AppsHyperscapeRouteContext {\n  req: http.IncomingMessage;\n  res: http.ServerResponse;\n  method: string;\n  pathname: string;\n  readJsonBody: <T extends object>(\n    req: http.IncomingMessage,\n    res: http.ServerResponse,\n  ) => Promise<T | null>;\n  error: (res: http.ServerResponse, message: string, status?: number) => void;\n  relayHyperscapeApi: (\n    method: \"GET\" | \"POST\",\n    path: string,\n    options?: HyperscapeRelayOptions,\n  ) => Promise<void>;\n}\n\nexport async function handleAppsHyperscapeRoutes(\n  ctx: AppsHyperscapeRouteContext,\n): Promise<boolean> {\n  const {\n    req,\n    res,\n    method,\n    pathname,\n    relayHyperscapeApi,\n    readJsonBody,\n    error,\n  } = ctx;\n\n  if (method === \"GET\" && pathname === \"/api/apps/hyperscape/embedded-agents\") {\n    await relayHyperscapeApi(\"GET\", \"/api/embedded-agents\");\n    return true;\n  }\n\n  if (\n    method === \"POST\" &&\n    pathname === \"/api/apps/hyperscape/embedded-agents\"\n  ) {\n    await relayHyperscapeApi(\"POST\", \"/api/embedded-agents\");\n    return true;\n  }\n\n  if (method === \"POST\") {\n    const embeddedActionMatch = pathname.match(\n      /^\\/api\\/apps\\/hyperscape\\/embedded-agents\\/([^/]+)\\/(start|stop|pause|resume|command)$/,\n    );\n    if (embeddedActionMatch) {\n      const characterId = decodeURIComponent(embeddedActionMatch[1]);\n      const action = embeddedActionMatch[2];\n      await relayHyperscapeApi(\n        \"POST\",\n        `/api/embedded-agents/${encodeURIComponent(characterId)}/${action}`,\n      );\n      return true;\n    }\n\n    const messageMatch = pathname.match(\n      /^\\/api\\/apps\\/hyperscape\\/agents\\/([^/]+)\\/message$/,\n    );\n    if (messageMatch) {\n      const agentId = decodeURIComponent(messageMatch[1]);\n      const body = await readJsonBody<{ content?: string }>(req, res);\n      if (!body) return true;\n      const content = body.content?.trim();\n      if (!content) {\n        error(res, \"content is required\");\n        return true;\n      }\n      await relayHyperscapeApi(\n        \"POST\",\n        `/api/embedded-agents/${encodeURIComponent(agentId)}/command`,\n        {\n          rawBodyOverride: JSON.stringify({\n            command: \"chat\",\n            data: { message: content },\n          }),\n          contentTypeOverride: \"application/json\",\n        },\n      );\n      return true;\n    }\n  }\n\n  if (method === \"GET\") {\n    const goalMatch = pathname.match(\n      /^\\/api\\/apps\\/hyperscape\\/agents\\/([^/]+)\\/goal$/,\n    );\n    if (goalMatch) {\n      const agentId = decodeURIComponent(goalMatch[1]);\n      await relayHyperscapeApi(\n        \"GET\",\n        `/api/agents/${encodeURIComponent(agentId)}/goal`,\n      );\n      return true;\n    }\n\n    const quickActionsMatch = pathname.match(\n      /^\\/api\\/apps\\/hyperscape\\/agents\\/([^/]+)\\/quick-actions$/,\n    );\n    if (quickActionsMatch) {\n      const agentId = decodeURIComponent(quickActionsMatch[1]);\n      await relayHyperscapeApi(\n        \"GET\",\n        `/api/agents/${encodeURIComponent(agentId)}/quick-actions`,\n      );\n      return true;\n    }\n  }\n\n  return false;\n}\n"],"mappings":";AAwBA,eAAsB,2BACpB,KACkB;AAClB,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,IAAI;AAEJ,MAAI,WAAW,SAAS,aAAa,wCAAwC;AAC3E,UAAM,mBAAmB,OAAO,sBAAsB;AACtD,WAAO;AAAA,EACT;AAEA,MACE,WAAW,UACX,aAAa,wCACb;AACA,UAAM,mBAAmB,QAAQ,sBAAsB;AACvD,WAAO;AAAA,EACT;AAEA,MAAI,WAAW,QAAQ;AACrB,UAAM,sBAAsB,SAAS;AAAA,MACnC;AAAA,IACF;AACA,QAAI,qBAAqB;AACvB,YAAM,cAAc,mBAAmB,oBAAoB,CAAC,CAAC;AAC7D,YAAM,SAAS,oBAAoB,CAAC;AACpC,YAAM;AAAA,QACJ;AAAA,QACA,wBAAwB,mBAAmB,WAAW,CAAC,IAAI,MAAM;AAAA,MACnE;AACA,aAAO;AAAA,IACT;AAEA,UAAM,eAAe,SAAS;AAAA,MAC5B;AAAA,IACF;AACA,QAAI,cAAc;AAChB,YAAM,UAAU,mBAAmB,aAAa,CAAC,CAAC;AAClD,YAAM,OAAO,MAAM,aAAmC,KAAK,GAAG;AAC9D,UAAI,CAAC,KAAM,QAAO;AAClB,YAAM,UAAU,KAAK,SAAS,KAAK;AACnC,UAAI,CAAC,SAAS;AACZ,cAAM,KAAK,qBAAqB;AAChC,eAAO;AAAA,MACT;AACA,YAAM;AAAA,QACJ;AAAA,QACA,wBAAwB,mBAAmB,OAAO,CAAC;AAAA,QACnD;AAAA,UACE,iBAAiB,KAAK,UAAU;AAAA,YAC9B,SAAS;AAAA,YACT,MAAM,EAAE,SAAS,QAAQ;AAAA,UAC3B,CAAC;AAAA,UACD,qBAAqB;AAAA,QACvB;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAEA,MAAI,WAAW,OAAO;AACpB,UAAM,YAAY,SAAS;AAAA,MACzB;AAAA,IACF;AACA,QAAI,WAAW;AACb,YAAM,UAAU,mBAAmB,UAAU,CAAC,CAAC;AAC/C,YAAM;AAAA,QACJ;AAAA,QACA,eAAe,mBAAmB,OAAO,CAAC;AAAA,MAC5C;AACA,aAAO;AAAA,IACT;AAEA,UAAM,oBAAoB,SAAS;AAAA,MACjC;AAAA,IACF;AACA,QAAI,mBAAmB;AACrB,YAAM,UAAU,mBAAmB,kBAAkB,CAAC,CAAC;AACvD,YAAM;AAAA,QACJ;AAAA,QACA,eAAe,mBAAmB,OAAO,CAAC;AAAA,MAC5C;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;","names":[]}

package/elizaos.plugin.json

@@ -0,0 +1,63 @@
+{
+  "id": "@elizaos/app-hyperscape",
+  "name": "Hyperscape",
+  "description": "AI-powered 3D multiplayer RPG — explore, fight, gather, craft, and socialize with AI agents",
+  "version": "1.0.0",
+  "kind": "app",
+  "configSchema": {
+    "HYPERSCAPE_SERVER_URL": {
+      "type": "string",
+      "description": "WebSocket URL for Hyperscape game server",
+      "default": "ws://localhost:5555/ws"
+    },
+    "HYPERSCAPE_CLIENT_URL": {
+      "type": "string",
+      "description": "URL for Hyperscape web client/viewer",
+      "default": "http://localhost:3333"
+    },
+    "HYPERSCAPE_AUTH_TOKEN": {
+      "type": "string",
+      "description": "Authentication token for Hyperscape"
+    },
+    "HYPERSCAPE_AUTO_RECONNECT": {
+      "type": "string",
+      "description": "Automatically reconnect on disconnect",
+      "default": "true"
+    },
+    "HYPERSCAPE_AUTONOMY_MODE": {
+      "type": "string",
+      "description": "Agent autonomy mode: llm, scripted, or hybrid",
+      "default": "llm"
+    }
+  },
+  "app": {
+    "displayName": "Hyperscape",
+    "category": "game",
+    "launchType": "connect",
+    "launchUrl": "http://localhost:3333",
+    "capabilities": [
+      "combat",
+      "skills",
+      "inventory",
+      "banking",
+      "social-chat",
+      "exploration",
+      "crafting"
+    ],
+    "maxPlayers": 100
+  },
+  "viewer": {
+    "url": "{HYPERSCAPE_CLIENT_URL}",
+    "embedParams": {
+      "embedded": "true",
+      "mode": "spectator",
+      "followEntity": "{HYPERSCAPE_CHARACTER_ID}"
+    },
+    "postMessageAuth": true,
+    "sandbox": "allow-scripts allow-same-origin allow-popups allow-forms"
+  },
+  "keywords": ["rpg", "3d", "multiplayer", "mmo", "game"],
+  "author": "Hyperscape Team",
+  "homepage": "https://hyperscape.ai",
+  "repository": "https://github.com/elizaos/app-hyperscape"
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@elizaos/app-hyperscape",
+  "version": "1.0.0",
+  "description": "Hyperscape — AI-powered 3D multiplayer RPG where agents explore, fight, gather, craft, and socialize",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "routes": [
+        "dist/routes.d.ts"
+      ],
+      "*": [
+        "dist/index.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./routes": {
+      "types": "./dist/routes.d.ts",
+      "import": "./dist/routes.js",
+      "default": "./dist/routes.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "elizaos.plugin.json"
+  ],
+  "keywords": [
+    "elizaos",
+    "app",
+    "hyperscape",
+    "rpg",
+    "3d",
+    "multiplayer",
+    "mmo",
+    "game"
+  ],
+  "dependencies": {
+    "@elizaos/core": "^2.0.0-alpha.2"
+  },
+  "devDependencies": {
+    "tsup": "8.3.5",
+    "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "build": "tsup --format esm --dts",
+    "dev": "tsup --format esm --dts --watch",
+    "clean": "rm -rf dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "elizaos": {
+    "kind": "app",
+    "app": {
+      "displayName": "Hyperscape",
+      "category": "game",
+      "launchType": "connect",
+      "launchUrl": "{HYPERSCAPE_CLIENT_URL}",
+      "capabilities": [
+        "combat",
+        "skills",
+        "inventory",
+        "banking",
+        "social-chat",
+        "exploration",
+        "crafting"
+      ]
+    },
+    "viewer": {
+      "url": "{HYPERSCAPE_CLIENT_URL}",
+      "postMessageAuth": true,
+      "sandbox": "allow-scripts allow-same-origin allow-popups allow-forms"
+    }
+  },
+  "license": "MIT"
+}