Metadata-Version: 2.4
Name: elizaos-plugin-roblox
Version: 2.0.0a5
Summary: Roblox plugin for elizaOS - Python implementation for game communication
Project-URL: Homepage, https://github.com/elizaos/eliza
Project-URL: Documentation, https://elizaos.ai/docs
Project-URL: Repository, https://github.com/elizaos/eliza
Project-URL: Issues, https://github.com/elizaos/eliza/issues
Author: elizaOS Contributors
License-Expression: MIT
Keywords: agent,ai,elizaos,gaming,metaverse,roblox
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.19.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest-xprocess>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.14.0; extra == 'dev'
Description-Content-Type: text/markdown

# elizaOS Roblox Plugin - Python Implementation

Python implementation of the Roblox plugin for elizaOS, enabling game communication via the Roblox Open Cloud API.

## Features

- **Messaging Service**: Cross-server communication with Roblox games
- **DataStore**: Persistent data storage operations
- **User Lookup**: Get player information by ID or username
- **Experience Info**: Retrieve universe/experience metadata
- **Dry Run Mode**: Test without making actual API calls
- **Fully Typed**: Complete type annotations with Pydantic models

## Installation

```bash
pip install elizaos-plugin-roblox
```

Or with development dependencies:

```bash
pip install elizaos-plugin-roblox[dev]
```

## Usage

```python
import asyncio
from uuid import uuid4
from elizaos_plugin_roblox import RobloxConfig, RobloxService

async def main():
    # Create config from environment or manually
    config = RobloxConfig.from_env()
    # Or: RobloxConfig(api_key="your-key", universe_id="12345")

    # Create and start service
    async with RobloxService(config, uuid4(), "MyAgent") as service:
        # Send a message to the game
        await service.send_message("Hello from Eliza!")

        # Execute a game action
        await service.execute_action(
            "spawn_item",
            {"item": "sword", "rarity": "legendary"},
            target_player_ids=[12345678],
        )

asyncio.run(main())
```

## Configuration

### Environment Variables

| Variable                 | Required | Description                              |
| ------------------------ | -------- | ---------------------------------------- |
| `ROBLOX_API_KEY`         | Yes      | Roblox Open Cloud API key                |
| `ROBLOX_UNIVERSE_ID`     | Yes      | Universe ID of the 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_POLL_INTERVAL`   | No       | Poll interval in seconds (default: 30)   |
| `ROBLOX_DRY_RUN`         | No       | Enable dry run mode (default: false)     |

## API Reference

### RobloxClient

Low-level API client:

```python
from elizaos_plugin_roblox import RobloxClient, RobloxConfig

async with RobloxClient(config) as client:
    # Messaging
    await client.publish_message("topic", data)
    await client.send_agent_message(message)

    # DataStore
    entry = await client.get_datastore_entry("store", "key")
    await client.set_datastore_entry("store", "key", value)
    await client.delete_datastore_entry("store", "key")

    # Users
    user = await client.get_user_by_id(12345678)
    user = await client.get_user_by_username("PlayerName")
    avatar = await client.get_avatar_url(12345678)

    # Experience
    info = await client.get_experience_info()
```

### RobloxService

High-level service for elizaOS integration:

```python
from elizaos_plugin_roblox import RobloxService

async with RobloxService(config, agent_id, "AgentName") as service:
    await service.send_message("Hello!")
    await service.execute_action("action_name", params)
```

## Development

### Setup

```bash
pip install -e ".[dev]"
```

### Testing

```bash
pytest
```

### Type Checking

```bash
mypy elizaos_plugin_roblox
```

### Linting

```bash
ruff check .
ruff format .
```

## License

MIT



