@elizaos/plugin-roblox 2.0.0-alpha.7 → 2.0.0-beta.1

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2024-2026 elizaOS
+
+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,186 @@
+# @elizaos/plugin-roblox
+
+Roblox plugin for elizaOS v2.0.0 - Enables AI agents to communicate with Roblox games via the Open Cloud API.
+
+## Features
+
+- **Messaging Service**: Cross-server communication with Roblox games
+- **DataStore Operations**: Persistent data storage for agents
+- **Player Management**: Look up player information by ID or username
+- **Game Actions**: Execute custom actions in-game
+- **Experience Info**: Retrieve game metadata and statistics
+
+## Installation
+
+### TypeScript
+
+```bash
+npm install @elizaos/plugin-roblox
+# or
+bun add @elizaos/plugin-roblox
+```
+## Quick Start
+
+### TypeScript (elizaOS)
+
+```typescript
+import { robloxPlugin } from "@elizaos/plugin-roblox";
+
+// Add to your agent configuration
+const agent = {
+  plugins: [robloxPlugin],
+  // ... other config
+};
+```
+
+### Environment Variables
+
+| Variable                 | Required | Description                              |
+| ------------------------ | -------- | ---------------------------------------- |
+| `ROBLOX_API_KEY`         | Yes      | Roblox Open Cloud API key                |
+| `ROBLOX_UNIVERSE_ID`     | Yes      | Universe ID of your experience           |
+| `ROBLOX_PLACE_ID`        | No       | Specific place ID                        |
+| `ROBLOX_WEBHOOK_SECRET`  | No       | Secret for webhook validation            |
+| `ROBLOX_MESSAGING_TOPIC` | No       | Messaging topic (default: "eliza-agent") |
+| `ROBLOX_DRY_RUN`         | No       | Enable dry run mode (default: false)     |
+
+## Action
+
+### ROBLOX_ACTION
+
+Route Roblox game integration through one compact action surface.
+
+Supported subactions:
+
+- `message`: send a message to all players or target player IDs
+- `execute`: publish a game-side action payload such as `spawn_entity`, `give_coins`, or `teleport`
+- `get_player`: look up Roblox player information by username or user ID
+
+**Examples:**
+
+- "Tell everyone in the game that there's a special event happening"
+- "Give player456 100 coins as a reward"
+- "Who is player 12345678?"
+
+## Providers
+
+### roblox-game-state
+
+Provides information about the connected Roblox experience to the agent's context:
+
+- Universe ID and Place ID
+- Experience name and statistics
+- Active player count
+- Creator information
+- Messaging topic configuration
+
+## Services
+
+### RobloxService
+
+Main service for managing Roblox connections and communication:
+
+```typescript
+import { RobloxService, ROBLOX_SERVICE_NAME } from "@elizaos/plugin-roblox";
+
+// Get service from runtime
+const service = runtime.getService<RobloxService>(ROBLOX_SERVICE_NAME);
+
+// Send a message to all players
+await service.sendMessage(runtime.agentId, "Hello from Eliza!");
+
+// Execute a game action
+await service.executeAction(
+  runtime.agentId,
+  "spawn_item",
+  { item: "sword", rarity: "legendary" },
+  [12345678], // Target specific player
+);
+```
+
+## Roblox Game Integration
+
+To receive messages from your Roblox game, you'll need to set up a Luau script that listens to the Messaging Service:
+
+```lua
+-- Server script in Roblox Studio
+local MessagingService = game:GetService("MessagingService")
+
+local TOPIC = "eliza-agent" -- Must match ROBLOX_MESSAGING_TOPIC
+
+MessagingService:SubscribeAsync(TOPIC, function(message)
+    local data = game:GetService("HttpService"):JSONDecode(message.Data)
+
+    if data.type == "agent_message" then
+        -- Handle agent message
+        print("Agent says:", data.content)
+        -- Broadcast to players, show in chat, etc.
+    elseif data.type == "agent_action" then
+        -- Handle agent action
+        print("Agent action:", data.action, data.parameters)
+        -- Execute the action in-game
+    end
+end)
+```
+
+## Limitations & recommended architecture (critical notes)
+
+### Inbound messages (Roblox → agent)
+
+Roblox Open Cloud **does not provide an external “subscribe” API** for `MessagingService`. That means:
+
+- This plugin supports **agent → Roblox** (publish) reliably.
+- It cannot, by itself, “listen to player chat” from outside Roblox by polling Open Cloud.
+
+**Recommended approach**: run a small HTTP bridge server that Roblox calls via `HttpService:RequestAsync(...)` and let the agent respond. See `examples/roblox/`.
+
+### Movement / “walking around”
+
+Agents cannot move things in Roblox via Open Cloud directly. Movement is possible only when your Roblox experience:
+
+- subscribes to the topic
+- interprets `agent_action` payloads (e.g. `move_npc`, `teleport`)
+- performs the movement using Roblox APIs (Humanoid / Pathfinding / TeleportService)
+
+### Voice
+
+Open Cloud does not provide a direct “agent voice” channel.
+
+- You can generate audio externally, but Roblox playback requires game-side logic and Roblox’s audio constraints (assets / permissions / allowed sources).
+- Most deployments start with **text** and add voice later with custom UI and an audio pipeline.
+
+## Project Structure
+
+```
+plugin-roblox/
+├── typescript/          # TypeScript implementation
+│   ├── actions/         # ROBLOX_ACTION router
+│   ├── services/        # RobloxService
+│   ├── providers/       # Context providers
+│   ├── client/          # API client
+│   ├── types/           # Type definitions
+│   └── index.ts         # Plugin entry point
+├── rust/                # Rust implementation
+│   └── src/
+│       ├── client.rs    # API client
+│       ├── service.rs   # Service implementation
+│       └── lib.rs       # Crate entry point
+├── python/              # Python implementation
+│   └── elizaos_plugin_roblox/
+│       ├── client.py    # API client
+│       ├── service.py   # Service implementation
+│       └── __init__.py  # Package entry point
+└── package.json         # npm package configuration
+```
+
+## Development
+
+### Building
+
+```bash
+# TypeScript
+bun run build
+# TypeScript
+bun run test
+# TypeScript
+bun run lint

package/dist/actions/executeGameAction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executeGameAction.d.ts","sourceRoot":"","sources":["../../actions/executeGameAction.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AAwIvB,QAAA,MAAM,iBAAiB,EAAE,MA2HxB,CAAC;AAEF,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"executeGameAction.d.ts","sourceRoot":"","sources":["../../actions/executeGameAction.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AAwIvB,QAAA,MAAM,iBAAiB,EAAE,MA0HxB,CAAC;AAEF,eAAe,iBAAiB,CAAC"}

package/dist/actions/executeRobloxAction.d.ts

@@ -0,0 +1,4 @@
+import { type Action } from "@elizaos/core";
+export declare const executeRobloxAction: Action;
+export default executeRobloxAction;
+//# sourceMappingURL=executeRobloxAction.d.ts.map

package/dist/actions/executeRobloxAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executeRobloxAction.d.ts","sourceRoot":"","sources":["../../actions/executeRobloxAction.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EAUZ,MAAM,eAAe,CAAC;AAiMvB,eAAO,MAAM,mBAAmB,EAAE,MA2GjC,CAAC;AAEF,eAAe,mBAAmB,CAAC"}

package/dist/actions/getPlayerInfo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getPlayerInfo.d.ts","sourceRoot":"","sources":["../../actions/getPlayerInfo.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AA4DvB,QAAA,MAAM,aAAa,EAAE,MAiKpB,CAAC;AAEF,eAAe,aAAa,CAAC"}
+{"version":3,"file":"getPlayerInfo.d.ts","sourceRoot":"","sources":["../../actions/getPlayerInfo.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AA4DvB,QAAA,MAAM,aAAa,EAAE,MAgKpB,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/dist/actions/index.d.ts

@@ -1,7 +1,5 @@
 import type { Action } from "@elizaos/core";
-import executeGameAction from "./executeGameAction";
-import getPlayerInfo from "./getPlayerInfo";
-import sendGameMessage from "./sendGameMessage";
+import robloxAction from "./robloxAction";
 export declare const robloxActions: Action[];
-export { sendGameMessage, executeGameAction, getPlayerInfo };
+export { robloxAction };
 //# sourceMappingURL=index.d.ts.map

package/dist/actions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../actions/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,iBAAiB,MAAM,qBAAqB,CAAC;AACpD,OAAO,aAAa,MAAM,iBAAiB,CAAC;AAC5C,OAAO,eAAe,MAAM,mBAAmB,CAAC;AAEhD,eAAO,MAAM,aAAa,EAAE,MAAM,EAAwD,CAAC;AAE3F,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../actions/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,YAAY,MAAM,gBAAgB,CAAC;AAE1C,eAAO,MAAM,aAAa,EAAE,MAAM,EAAmB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/actions/robloxAction.d.ts

@@ -0,0 +1,4 @@
+import { type Action } from "@elizaos/core";
+export declare const robloxAction: Action;
+export default robloxAction;
+//# sourceMappingURL=robloxAction.d.ts.map

package/dist/actions/robloxAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"robloxAction.d.ts","sourceRoot":"","sources":["../../actions/robloxAction.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EAUZ,MAAM,eAAe,CAAC;AA+YvB,eAAO,MAAM,YAAY,EAAE,MAmI1B,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/actions/sendGameMessage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sendGameMessage.d.ts","sourceRoot":"","sources":["../../actions/sendGameMessage.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AAuCvB,QAAA,MAAM,eAAe,EAAE,MA4HtB,CAAC;AAaF,eAAe,eAAe,CAAC"}
+{"version":3,"file":"sendGameMessage.d.ts","sourceRoot":"","sources":["../../actions/sendGameMessage.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AAuCvB,QAAA,MAAM,eAAe,EAAE,MA2HtB,CAAC;AAaF,eAAe,eAAe,CAAC"}

package/dist/actions/sendRobloxMessage.d.ts

@@ -0,0 +1,4 @@
+import { type Action } from "@elizaos/core";
+export declare const sendRobloxMessage: Action;
+export default sendRobloxMessage;
+//# sourceMappingURL=sendRobloxMessage.d.ts.map

package/dist/actions/sendRobloxMessage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sendRobloxMessage.d.ts","sourceRoot":"","sources":["../../actions/sendRobloxMessage.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AA0FvB,eAAO,MAAM,iBAAiB,EAAE,MAkG/B,CAAC;AAEF,eAAe,iBAAiB,CAAC"}

package/dist/generated/specs/specs.d.ts

@@ -1,5 +1,5 @@
 /**
- * Auto-generated canonical action/provider/evaluator docs for plugin-roblox.
+ * Auto-generated canonical action/provider docs for plugin-roblox.
  * DO NOT EDIT - Generated from prompts/specs/**.
  */
 export type ActionDoc = {
@@ -15,13 +15,6 @@ export type ProviderDoc = {
     position?: number;
     dynamic?: boolean;
 };
-export type EvaluatorDoc = {
-    name: string;
-    description: string;
-    similes?: readonly string[];
-    alwaysRun?: boolean;
-    examples?: readonly unknown[];
-};
 export declare const coreActionsSpec: {
     readonly version: "1.0.0";
     readonly actions: readonly [];
@@ -46,18 +39,8 @@ export declare const allProvidersSpec: {
         readonly dynamic: true;
     }];
 };
-export declare const coreEvaluatorsSpec: {
-    readonly version: "1.0.0";
-    readonly evaluators: readonly [];
-};
-export declare const allEvaluatorsSpec: {
-    readonly version: "1.0.0";
-    readonly evaluators: readonly [];
-};
 export declare const coreActionDocs: readonly ActionDoc[];
 export declare const allActionDocs: readonly ActionDoc[];
 export declare const coreProviderDocs: readonly ProviderDoc[];
 export declare const allProviderDocs: readonly ProviderDoc[];
-export declare const coreEvaluatorDocs: readonly EvaluatorDoc[];
-export declare const allEvaluatorDocs: readonly EvaluatorDoc[];
 //# sourceMappingURL=specs.d.ts.map

package/dist/generated/specs/specs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"specs.d.ts","sourceRoot":"","sources":["../../../generated/specs/specs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,SAAS,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC/B,CAAC;AAEF,eAAO,MAAM,eAAe;;;CAGlB,CAAC;AACX,eAAO,MAAM,cAAc;;;CAGjB,CAAC;AACX,eAAO,MAAM,iBAAiB;;;;;;;CASpB,CAAC;AACX,eAAO,MAAM,gBAAgB;;;;;;;CASnB,CAAC;AACX,eAAO,MAAM,kBAAkB;;;CAGrB,CAAC;AACX,eAAO,MAAM,iBAAiB;;;CAGpB,CAAC;AAEX,eAAO,MAAM,cAAc,EAAE,SAAS,SAAS,EAA4B,CAAC;AAC5E,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAA2B,CAAC;AAC1E,eAAO,MAAM,gBAAgB,EAAE,SAAS,WAAW,EAAgC,CAAC;AACpF,eAAO,MAAM,eAAe,EAAE,SAAS,WAAW,EAA+B,CAAC;AAClF,eAAO,MAAM,iBAAiB,EAAE,SAAS,YAAY,EAAkC,CAAC;AACxF,eAAO,MAAM,gBAAgB,EAAE,SAAS,YAAY,EAAiC,CAAC"}
+{"version":3,"file":"specs.d.ts","sourceRoot":"","sources":["../../../generated/specs/specs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,SAAS,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,eAAe;;;CAGlB,CAAC;AACX,eAAO,MAAM,cAAc;;;CAGjB,CAAC;AACX,eAAO,MAAM,iBAAiB;;;;;;;CASpB,CAAC;AACX,eAAO,MAAM,gBAAgB;;;;;;;CASnB,CAAC;AAEX,eAAO,MAAM,cAAc,EAAE,SAAS,SAAS,EAA4B,CAAC;AAC5E,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAA2B,CAAC;AAC1E,eAAO,MAAM,gBAAgB,EAAE,SAAS,WAAW,EAAgC,CAAC;AACpF,eAAO,MAAM,eAAe,EAAE,SAAS,WAAW,EAA+B,CAAC"}