{"_id":"@elizaos/plugin-roblox-root","_rev":"4-c89b544366b5d61d8c6953ace232d372","name":"@elizaos/plugin-roblox-root","dist-tags":{"next":"2.0.0-alpha.1","latest":"2.0.0-alpha.1"},"versions":{"2.0.0-alpha.1":{"name":"@elizaos/plugin-roblox-root","version":"2.0.0-alpha.1","keywords":[],"author":{"name":"elizaOS"},"license":"MIT","_id":"@elizaos/plugin-roblox-root@2.0.0-alpha.1","maintainers":[{"name":"shawticus","email":"shawmakesmagic@gmail.com"},{"name":"shakkernerd","email":"shakkerdroid@gmail.com"},{"name":"wtfsayo","email":"hi@sayo.wtf"},{"name":"odilitime","email":"janesmith@airmail.cc"},{"name":"cjft","email":"cjft@trimboli.io"}],"homepage":"https://github.com/elizaos-plugins/plugin-roblox#readme","bugs":{"url":"https://github.com/elizaos-plugins/plugin-roblox/issues"},"dist":{"shasum":"f470610b83cc2f9a5ff83777a72d82c8a5654cc7","tarball":"https://registry.npmjs.org/@elizaos/plugin-roblox-root/-/plugin-roblox-root-2.0.0-alpha.1.tgz","fileCount":103,"integrity":"sha512-/uSO6aN4+Q8iCsbal8w9V8mkyZXmZ0n3dp4HRr76FDnF4Pspgn5Y7KqCSnNlrDfndbuppemIKNRtUckdljnVRw==","signatures":[{"sig":"MEQCIEIxJTpi+uGhYwsxDiTRC/QFaP9bPHR5Yt+WZtOtjO39AiBmrltQyzgypAHLDHCDjurzyDTdTlUOU9wkLSOwv+uLSA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":424442},"main":"typescript/dist/index.js","type":"module","types":"typescript/dist/index.d.ts","exports":{".":{"types":"./typescript/dist/index.d.ts","import":"./typescript/dist/index.js","default":"./typescript/dist/index.js"},"./rust":{"import":"./rust/pkg/node/elizaos_plugin_plugin_roblox.js"},"./package.json":"./package.json"},"gitHead":"05d4ca11d769db8c7f54a722ee24b2ce2b951543","scripts":{"dev":"cd typescript && bun --hot build.ts","lint":"bunx @biomejs/biome check --write ./typescript","test":"bun run test:ts && bun run test:rust && bun run test:python","build":"bun run build:ts && bun run build:rust && bun run build:python","clean":"rm -rf typescript/dist python/dist rust/target .turbo node_modules","test:ts":"cd typescript && vitest run || echo 'TypeScript tests skipped - no tests found'","build:ts":"cd typescript && bun run build.ts","lint:rust":"test -d rust && cd rust && cargo clippy --all-targets --fix --allow-dirty --allow-staged -- -D warnings && cargo fmt || echo 'Rust lint skipped'","test:rust":"test -d rust && cd rust && cargo test || echo 'Rust tests skipped'","typecheck":"tsc --noEmit -p typescript/tsconfig.json","build:rust":"test -d rust && cd rust && cargo build --release || echo 'Rust build skipped - no rust directory'","lint:check":"bunx @biomejs/biome check ./typescript","lint:python":"test -d python && cd python && ruff check --fix . && ruff format . || echo 'Python lint skipped'","test:python":"test -d python && cd python && pytest -p no:anchorpy --asyncio-mode=auto || echo 'Python tests skipped'","build:python":"test -d python && cd python && (python3 -m build 2>/dev/null || pyproject-build) || echo 'Python build skipped - no python directory'","lint:python:fix":"test -d python && cd python && ruff check --fix . && ruff format . || echo 'Python lint fix skipped'"},"_npmUser":{"name":"shawticus","email":"shawmakesmagic@gmail.com"},"repository":{"url":"git+https://github.com/elizaos-plugins/plugin-roblox.git","type":"git"},"_npmVersion":"lerna/9.0.3/node@v22.20.0+arm64 (darwin)","agentConfig":{"pluginType":"elizaos:plugin:1.0.0","pluginParameters":{"ROBLOX_API_KEY":{"type":"string","required":true,"sensitive":true,"description":"API key for authenticating with the Roblox Open Cloud API."},"ROBLOX_DRY_RUN":{"type":"boolean","default":false,"required":false,"sensitive":false,"description":"When true, operations are simulated but not executed."},"ROBLOX_PLACE_ID":{"type":"string","required":false,"sensitive":false,"description":"The Place ID of the specific Roblox place within the universe."},"ROBLOX_UNIVERSE_ID":{"type":"string","required":true,"sensitive":false,"description":"The Universe ID of the Roblox experience to interact with."},"ROBLOX_POLL_INTERVAL":{"type":"number","default":30,"required":false,"sensitive":false,"description":"Polling interval in seconds for Roblox data store operations."},"ROBLOX_WEBHOOK_SECRET":{"type":"string","required":false,"sensitive":true,"description":"Secret key for validating incoming webhooks from Roblox."},"ROBLOX_MESSAGING_TOPIC":{"type":"string","default":"eliza-agent","required":false,"sensitive":false,"description":"The messaging service topic for cross-server communication."}}},"description":"Roblox plugin for elizaOS v2.0.0 - Enables AI agents to communicate with Roblox games via the Open Cloud API.","directories":{},"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.3.5","typescript":"^5.9.3","@types/node":"^25.0.3","@biomejs/biome":"^2.3.11"},"peerDependencies":{"@elizaos/core":"2.0.0-alpha.1"},"_npmOperationalInternal":{"tmp":"tmp/plugin-roblox-root_2.0.0-alpha.1_1769034086403_0.10162877010303384","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-01-21T22:21:26.248Z","modified":"2026-06-16T05:15:03.912Z","2.0.0-alpha.1":"2026-01-21T22:21:26.590Z"},"bugs":{"url":"https://github.com/elizaos-plugins/plugin-roblox/issues"},"author":{"name":"elizaOS"},"license":"MIT","homepage":"https://github.com/elizaos-plugins/plugin-roblox#readme","keywords":[],"repository":{"url":"git+https://github.com/elizaos-plugins/plugin-roblox.git","type":"git"},"description":"Roblox plugin for elizaOS v2.0.0 - Enables AI agents to communicate with Roblox games via the Open Cloud API.","maintainers":[{"email":"shawmakesmagic@gmail.com","name":"shawticus"},{"email":"janesmith@airmail.cc","name":"odilitime"}],"readme":"# @elizaos/plugin-roblox\n\nRoblox plugin for elizaOS v2.0.0 - Enables AI agents to communicate with Roblox games via the Open Cloud API.\n\n## Features\n\n- **Messaging Service**: Cross-server communication with Roblox games\n- **DataStore Operations**: Persistent data storage for agents\n- **Player Management**: Look up player information by ID or username\n- **Game Actions**: Execute custom actions in-game\n- **Experience Info**: Retrieve game metadata and statistics\n- **Multi-Language**: Available in TypeScript, Rust, and Python\n\n## Installation\n\n### TypeScript\n\n```bash\nnpm install @elizaos/plugin-roblox\n# or\nbun add @elizaos/plugin-roblox\n```\n\n### Rust\n\n```toml\n[dependencies]\nelizaos-plugin-roblox = \"2.0\"\n```\n\n### Python\n\n```bash\npip install elizaos-plugin-roblox\n```\n\n## Quick Start\n\n### TypeScript (elizaOS)\n\n```typescript\nimport { robloxPlugin } from \"@elizaos/plugin-roblox\";\n\n// Add to your agent configuration\nconst agent = {\n  plugins: [robloxPlugin],\n  // ... other config\n};\n```\n\n### Environment Variables\n\n| Variable                 | Required | Description                              |\n| ------------------------ | -------- | ---------------------------------------- |\n| `ROBLOX_API_KEY`         | Yes      | Roblox Open Cloud API key                |\n| `ROBLOX_UNIVERSE_ID`     | Yes      | Universe ID of your experience           |\n| `ROBLOX_PLACE_ID`        | No       | Specific place ID                        |\n| `ROBLOX_WEBHOOK_SECRET`  | No       | Secret for webhook validation            |\n| `ROBLOX_MESSAGING_TOPIC` | No       | Messaging topic (default: \"eliza-agent\") |\n| `ROBLOX_POLL_INTERVAL`   | No       | Poll interval in seconds (default: 30)   |\n| `ROBLOX_DRY_RUN`         | No       | Enable dry run mode (default: false)     |\n\n## Actions\n\n### SEND_ROBLOX_MESSAGE\n\nSend a message to players in a Roblox game.\n\n**Examples:**\n\n- \"Tell everyone in the game that there's a special event happening\"\n- \"Send a welcome message to player123\"\n\n### EXECUTE_ROBLOX_ACTION\n\nExecute a custom action in a Roblox game.\n\n**Examples:**\n\n- \"Start a fireworks show in the game\"\n- \"Give player456 100 coins as a reward\"\n- \"Teleport everyone to the lobby\"\n\n### GET_ROBLOX_PLAYER\n\nLook up information about a Roblox player.\n\n**Examples:**\n\n- \"Who is player 12345678?\"\n- \"Look up the Roblox user JohnDoe123\"\n\n## Providers\n\n### roblox-game-state\n\nProvides information about the connected Roblox experience to the agent's context:\n\n- Universe ID and Place ID\n- Experience name and statistics\n- Active player count\n- Creator information\n- Messaging topic configuration\n\n## Services\n\n### RobloxService\n\nMain service for managing Roblox connections and communication:\n\n```typescript\nimport { RobloxService, ROBLOX_SERVICE_NAME } from \"@elizaos/plugin-roblox\";\n\n// Get service from runtime\nconst service = runtime.getService<RobloxService>(ROBLOX_SERVICE_NAME);\n\n// Send a message to all players\nawait service.sendMessage(runtime.agentId, \"Hello from Eliza!\");\n\n// Execute a game action\nawait service.executeAction(\n  runtime.agentId,\n  \"spawn_item\",\n  { item: \"sword\", rarity: \"legendary\" },\n  [12345678], // Target specific player\n);\n```\n\n## Roblox Game Integration\n\nTo receive messages from your Roblox game, you'll need to set up a Luau script that listens to the Messaging Service:\n\n```lua\n-- Server script in Roblox Studio\nlocal MessagingService = game:GetService(\"MessagingService\")\n\nlocal TOPIC = \"eliza-agent\" -- Must match ROBLOX_MESSAGING_TOPIC\n\nMessagingService:SubscribeAsync(TOPIC, function(message)\n    local data = game:GetService(\"HttpService\"):JSONDecode(message.Data)\n\n    if data.type == \"agent_message\" then\n        -- Handle agent message\n        print(\"Agent says:\", data.content)\n        -- Broadcast to players, show in chat, etc.\n    elseif data.type == \"agent_action\" then\n        -- Handle agent action\n        print(\"Agent action:\", data.action, data.parameters)\n        -- Execute the action in-game\n    end\nend)\n```\n\n## Limitations & recommended architecture (critical notes)\n\n### Inbound messages (Roblox → agent)\n\nRoblox Open Cloud **does not provide an external “subscribe” API** for `MessagingService`. That means:\n\n- This plugin supports **agent → Roblox** (publish) reliably.\n- It cannot, by itself, “listen to player chat” from outside Roblox by polling Open Cloud.\n\n**Recommended approach**: run a small HTTP bridge server that Roblox calls via `HttpService:RequestAsync(...)` and let the agent respond. See `examples/roblox/`.\n\n### Movement / “walking around”\n\nAgents cannot move things in Roblox via Open Cloud directly. Movement is possible only when your Roblox experience:\n\n- subscribes to the topic\n- interprets `agent_action` payloads (e.g. `move_npc`, `teleport`)\n- performs the movement using Roblox APIs (Humanoid / Pathfinding / TeleportService)\n\n### Voice\n\nOpen Cloud does not provide a direct “agent voice” channel.\n\n- You can generate audio externally, but Roblox playback requires game-side logic and Roblox’s audio constraints (assets / permissions / allowed sources).\n- Most deployments start with **text** and add voice later with custom UI and an audio pipeline.\n\n## Project Structure\n\n```\nplugin-roblox/\n├── typescript/          # TypeScript implementation\n│   ├── actions/         # Agent actions\n│   ├── services/        # RobloxService\n│   ├── providers/       # Context providers\n│   ├── client/          # API client\n│   ├── types/           # Type definitions\n│   └── index.ts         # Plugin entry point\n├── rust/                # Rust implementation\n│   └── src/\n│       ├── client.rs    # API client\n│       ├── service.rs   # Service implementation\n│       └── lib.rs       # Crate entry point\n├── python/              # Python implementation\n│   └── elizaos_plugin_roblox/\n│       ├── client.py    # API client\n│       ├── service.py   # Service implementation\n│       └── __init__.py  # Package entry point\n└── package.json         # npm package configuration\n```\n\n## Development\n\n### Building\n\n```bash\n# TypeScript\nbun run build\n\n# Rust\nbun run build:rust\n\n# Python\npip install -e \"python/[dev]\"\n```\n\n### Testing\n\n```bash\n# TypeScript\nbun run test\n\n# Rust\nbun run test:rust\n\n# Python\ncd python && pytest\n```\n\n### Linting\n\n```bash\n# TypeScript\nbun run lint\n\n# Rust\nbun run lint:rust\n\n# Python\nbun run lint:python\n```\n\n## API Reference\n\n### TypeScript\n\nSee [typescript/](./typescript/) for the full TypeScript API.\n\n### Rust\n\nSee [rust/README.md](./rust/README.md) for the Rust API documentation.\n\n### Python\n\nSee [python/README.md](./python/README.md) for the Python API documentation.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests (`bun run test`)\n5. Submit a pull request\n\n## License\n\nMIT\n\n## Related Links\n\n- [Roblox Open Cloud API](https://create.roblox.com/docs/cloud)\n- [elizaOS Documentation](https://elizaos.ai/docs)\n- [Plugin Architecture Guide](.cursor/rules/elizaos/elizaos_client_plugins.mdc)\n\n\n\n","readmeFilename":"README.md"}