@elizaos/plugin-companion 2.0.11-beta.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# @elizaos/plugin-companion
+
+Companion overlay plugin for elizaOS. Adds a 3D VRM avatar to an Eliza agent, with animated emotes, a chat overlay, and performance controls — rendered in a Three.js scene directly on the agent surface.
+
+## What it does
+
+- Renders a VRM (Virtual Reality Model) avatar in a 3D Three.js scene on the agent's companion surface.
+- Enables the agent to play named emote animations via the `PLAY_EMOTE` action (wave, dance, cry, salute, and ~35 others).
+- Provides three view surfaces: standard overlay, XR overlay, and a terminal (TUI) view.
+- Bridges live agent state (chat messages, agent status, active coding sessions, triggers/heartbeats) into in-scene overlays rendered above the avatar.
+- Ships a full emote catalog (`EMOTE_CATALOG`) of GLB and Mixamo FBX animations, all served as gzip-compressed assets.
+
+## Capabilities added to the agent
+
+### `PLAY_EMOTE` action
+
+The agent can call this action to play a one-shot emote on the VRM avatar. It is silent — it does not generate chat text — and is intended to run alongside speech or reply actions.
+
+Valid emote IDs (sample):
+
+| ID | Description |
+|----|-------------|
+| `wave` | Waves both hands in greeting |
+| `dance-happy` | Happy dance (loops) |
+| `gangnam-style` | Gangnam style dance (loops) |
+| `crying` | Cries sadly (loops) |
+| `angry` | Expresses anger |
+| `thinking` | Hand-to-chin thinking (loops) |
+| `salute` | Sharp salute |
+| `joyful-jump` | Jumps for joy |
+
+Full catalog: `src/emotes/catalog.ts` — `AGENT_EMOTE_CATALOG` lists all IDs the agent can use.
+
+## Required configuration
+
+No env vars are required for basic use. Optional:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `API_PORT` | `2138` | Port of the agent dashboard API server for emote delivery |
+| `SERVER_PORT` | `2138` | Fallback if `API_PORT` is not set |
+
+To disable emote playback for a specific character, set `character.settings.DISABLE_EMOTES` to any truthy value in the character configuration.
+
+## How to enable
+
+Add `@elizaos/plugin-companion` to the agent's plugin list. The plugin is session-gated — it only activates when the agent session is scoped to the companion app context.
+
+```ts
+import { appCompanionPlugin } from "@elizaos/plugin-companion";
+
+// In your agent character/plugin config:
+plugins: [appCompanionPlugin]
+```
+
+Alternatively, to register the companion as an overlay app (for hosts that use the overlay app registry):
+
+```ts
+import "@elizaos/plugin-companion/register"; // side-effect: calls registerCompanionApp()
+// or explicitly:
+import { registerCompanionApp } from "@elizaos/plugin-companion";
+registerCompanionApp();
+```
+
+## Peer dependencies
+
+Three.js, `@pixiv/three-vrm`, `react`, and `react-dom` must be installed by the host:
+
+```bash
+bun add three @pixiv/three-vrm react react-dom
+```
+
+## Build
+
+```bash
+bun run --cwd plugins/plugin-companion build        # full build (JS + views bundle + types)
+bun run --cwd plugins/plugin-companion build:views  # Vite bundle for companion view components
+bun run --cwd plugins/plugin-companion typecheck
+bun run --cwd plugins/plugin-companion test
+```

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@elizaos/plugin-companion",
+  "version": "2.0.11-beta.7",
+  "type": "module",
+  "description": "Companion app package with the VRM scene runtime and avatar utilities.",
+  "main": "./dist/index.js",
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "bunx @biomejs/biome check src/",
+    "test": "bunx vitest run --config ./vitest.config.ts",
+    "storybook": "storybook dev -p 6007",
+    "build-storybook": "storybook build",
+    "build": "bun run build:js && bun run build:views && bun run build:types",
+    "clean": "rm -rf dist",
+    "build:js": "tsup --config ../tsup.plugin-packages.shared.ts",
+    "build:views": "bunx --bun vite build --config vite.config.views.ts",
+    "build:types": "tsc --noCheck -p tsconfig.build.json"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "dependencies": {
+    "@elizaos/agent": "2.0.11-beta.7",
+    "@elizaos/app-core": "2.0.11-beta.7",
+    "@elizaos/core": "2.0.11-beta.7",
+    "@elizaos/plugin-wallet-ui": "2.0.11-beta.7",
+    "@elizaos/shared": "2.0.11-beta.7",
+    "@elizaos/ui": "2.0.11-beta.7",
+    "lucide-react": "^1.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@pixiv/three-vrm": "^3.5.2",
+    "@playwright/test": "^1.58.2",
+    "@storybook/addon-a11y": "^10.0.0",
+    "@storybook/addon-docs": "^10.0.0",
+    "@storybook/addon-themes": "^10.0.0",
+    "@storybook/react": "^10.0.0",
+    "@storybook/react-vite": "^10.0.0",
+    "@types/node": "^25.0.6",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@types/three": "^0.184.0",
+    "dotenv": "^17.2.3",
+    "jsdom": "^29.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "storybook": "^10.0.0",
+    "three": "^0.184.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.0",
+    "vitest": "^4.0.17"
+  },
+  "peerDependencies": {
+    "@pixiv/three-vrm": "^3.4.5",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "three": "^0.184.0"
+  },
+  "elizaos": {
+    "app": {
+      "displayName": "Eliza Companion",
+      "category": "game",
+      "heroImage": "assets/hero.png"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "gitHead": "cdbc876f793d96073d7eb0d09715a031ce0cd32e"
+}