PolyRob

Automated workflow for converting 3D scans from iPhone (Polycam) to Roblox assets with optional Studio integration and marketplace publishing support.

🚀 Features

• Automated Download: Downloads latest 3D models from Polycam using browser automation
• Direct Upload: Uploads models to Roblox via Open Cloud Assets API
• Studio Integration: Optional automatic insertion into Roblox Studio workspace via MCP
• Marketplace Support: Metadata updates and instructions for Creator Marketplace publishing
• Modern Tooling: Uses uv for fast Python package management
• Environment Config: Supports .env files for secure credential management

📋 Prerequisites

• iPhone with LiDAR (iPhone 12 Pro or newer)
• Polycam app installed on iPhone
• Polycam account (Pro or Enterprise subscription required for .fbx export)
• Roblox account with Open Cloud API key
• Python 3.12+ installed on your computer
• Roblox Studio (optional, for Studio integration)

🛠️ Installation

1. Clone the repository:

   git clone https://github.com/yourusername/polyrob.git
   cd polyrob

2. Run the setup script:

   bash setup.sh

   This will:

   • Check for Python 3.12+
   • Install uv if needed
   • Install Python dependencies
   • Install Playwright browsers
   • Make scripts executable

3. Configure your credentials:

   cp .env.example .env
   nano .env  # or use your preferred editor

   Required environment variables:

   POLYCAM_EMAIL="your-email@example.com"
   POLYCAM_PASSWORD="your-password"
   ROBLOX_API_KEY="your-roblox-api-key"
   ROBLOX_USER_ID="your-roblox-user-id"

   To get your Roblox API Key:

   • Go to Creator Hub
   • Click "Credentials" in the left menu
   • Create a new API key with "Asset" permissions (Read and Write)

🎯 Usage

Basic Workflow

1. Scan an object with Polycam on your iPhone

2. Sync the scan to your Polycam account (automatic)

3. Run the automation:

   uv run full_automation.py

   Or use Python directly:

   python3 full_automation.py

The script will:

• Download the latest scan from Polycam
• Upload it to Roblox
• Optionally insert it into Studio (if MCP is configured)
• Provide marketplace publishing instructions

Optional Configuration

Marketplace Publishing:

export ROBLOX_MARKETPLACE_ENABLED="true"
export ROBLOX_ASSET_PRICE="100"  # Desired price in Robux
export ROBLOX_ASSET_DESCRIPTION="Your asset description"
export ROBLOX_UPDATE_METADATA="true"

Studio Integration:

export ROBLOX_STUDIO_INTEGRATION="true"   # Enable (default)
export ROBLOX_STUDIO_INTEGRATION="false"  # Disable

Custom Download Directory:

export DOWNLOAD_DIR="/path/to/downloads"

📁 Project Structure

polyrob/
├── full_automation.py          # Main automation script
├── polycam_downloader.py       # Polycam download module
├── scan_to_roblox.py           # Roblox upload module
├── roblox_studio_mcp.py        # Studio MCP integration helper
├── pyproject.toml              # UV project configuration
├── requirements.txt             # Legacy dependencies (for compatibility)
├── setup.sh                     # Installation script
├── .python-version              # Python version (3.12)
├── .env.example                 # Example environment file
├── README.md                    # This file
├── Automated 3D Scan to Roblox Workflow.md  # Detailed documentation
├── Automated 3D Scan to Roblox Workflow Architecture.md  # Architecture docs
└── 3D Scanning Apps Research.md # Research notes

🔧 Roblox Studio Integration

If you have Roblox Studio MCP configured (available in Cursor IDE), the script can automatically insert uploaded assets into your Studio workspace.

How it works:

1. After uploading, the script generates Lua code for insertion
2. If MCP is available, it can automatically insert via mcp_Roblox_Studio_run_code
3. Otherwise, it provides Lua code that you can paste into Studio's Command Bar

Manual insertion in Studio:

1. Open Roblox Studio
2. Open Command Bar (View > Command Bar or Ctrl+/)
3. Paste the Lua code provided by the script
4. Press Enter to execute

📝 Marketplace Publishing

Important: Roblox's Open Cloud API does not currently support programmatic marketplace publishing or price setting. These operations must be done manually through the Roblox Creator Dashboard.

However, the script can:

• Upload your asset to Roblox
• Update asset metadata (name, description)
• Provide detailed instructions for manual marketplace publishing

🐛 Troubleshooting

Playwright browser not found:

uv run playwright install chromium

Python version error: Ensure you have Python 3.12 or higher:

python3 --version

Import errors: Make sure dependencies are installed:

uv sync

Polycam login issues:

• First run may require CAPTCHA solving
• Browser will use cookies for subsequent runs
• Check your Polycam credentials

📚 Documentation

• Automated 3D Scan to Roblox Workflow - Complete workflow documentation
• Architecture Documentation - System architecture details
• 3D Scanning Apps Research - Research on scanning apps and Roblox integration

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

• Polycam for 3D scanning capabilities
• Roblox Open Cloud for API access
• UV for fast Python package management
• Playwright for browser automation

⚠️ Limitations

• Marketplace publishing requires manual steps via Creator Dashboard
• Asset prices cannot be set programmatically
• Requires Polycam Pro/Enterprise for FBX export
• File size limit: 20 MB per asset (Roblox limitation)

🔮 Future Enhancements

• GUI interface for easier use
• Scheduled runs to check for new scans automatically
• Support for other 3D scanning apps
• Batch processing multiple scans
• Direct marketplace publishing (when API support is available)