ShapeForge for Roblox

🎮 Text-to-3D generation app for Roblox using OpenAI's Shap-E

Transform your ideas into Roblox-ready 3D models using natural language descriptions!

Features

• 🚀 Fast 3D Generation: Create 3D models from text in seconds
• 🎯 Roblox Optimized: Automatic optimization for Roblox requirements (≤10k triangles, watertight meshes)
• 🎨 Multiple Formats: Export to OBJ, FBX, and GLTF
• 🖥️ User-Friendly Interface: Clean web interface with real-time preview
• ⚡ Background Processing: Async generation with progress tracking
• 📱 Responsive Design: Works on desktop and mobile

Quick Start

Prerequisites

• Python 3.8+
• Node.js 16+
• Git

Installation

1. Clone the repository

git clone <your-repo-url>
cd shap-e

2. Run the setup script

python setup.py

3. Start the backend

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Start the API server
python src/api_server.py

4. Start the frontend (in a new terminal)

cd frontend
npm run dev

5. Open your browser Navigate to http://localhost:3000

Usage

1. Enter a description of your 3D object (e.g., "a medieval sword with golden handle")
2. Choose export format (OBJ recommended for Roblox)
3. Click Generate and wait for processing
4. Download your Roblox-ready 3D model!

Importing to Roblox Studio

1. Download your generated model
2. Open Roblox Studio
3. Go to Avatar tab → 3D Importer
4. Select your downloaded file
5. Click Import!

Example Prompts

• "a futuristic spaceship with glowing engines"
• "a wooden treasure chest with golden clasps"
• "a cartoon-style robot with blue accents"
• "a magical staff with crystal orb"
• "a racing car with spoiler, low-poly style"

API Endpoints

• POST /api/generate - Start 3D generation
• GET /api/jobs/{job_id} - Check generation status
• GET /api/jobs - List all jobs
• GET /download/{filename} - Download generated model

Technical Details

Shap-E Integration

• Uses OpenAI's Shap-E for text-to-3D generation
• Leverages conditional implicit neural representations
• Fast generation (seconds to minutes vs hours)

Roblox Optimization Pipeline

• Triangle Reduction: Automatically reduces to ≤10,000 triangles
• Mesh Cleanup: Removes degenerate faces and duplicate vertices
• Watertight Validation: Ensures meshes are properly closed
• Format Conversion: Exports in Roblox-compatible formats

Architecture

Frontend (React) → FastAPI Backend → Shap-E → Mesh Optimization → Export

Configuration

Environment Variables

Create a .env file:

CUDA_VISIBLE_DEVICES=0  # For GPU acceleration
MAX_CONCURRENT_JOBS=2   # Limit concurrent generations

Generation Parameters

• Guidance Scale: Controls adherence to prompt (1-30, default: 15)
• Max Triangles: Triangle limit for Roblox (100-10000)
• Target Format: Output format (obj/fbx/gltf)

Troubleshooting

Common Issues

1. CUDA Out of Memory

   • Reduce batch_size in generation config
   • Use CPU if GPU memory is limited

2. Shap-E Models Not Found

   • Models download automatically on first use
   • Ensure stable internet connection

3. Frontend Build Errors

   • Run npm install in frontend directory
   • Check Node.js version (16+ required)

4. Import to Roblox Fails

   • Ensure model file size < 50MB
   • Try different export format (OBJ usually most compatible)

Development

Project Structure

shap-e/
├── src/
│   ├── shapeforge_core.py    # Core 3D generation logic
│   └── api_server.py         # FastAPI backend
├── frontend/
│   ├── src/
│   │   ├── App.jsx          # Main React component
│   │   └── main.jsx         # React entry point
│   └── package.json
├── requirements.txt          # Python dependencies
└── setup.py                 # Setup script

Adding New Features

1. New Export Format: Extend RobloxExportPipeline class
2. Custom Optimization: Modify RobloxMeshOptimizer class
3. UI Improvements: Edit React components in frontend/src/

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - See LICENSE file for details

Acknowledgments

• OpenAI Shap-E for the core 3D generation
• Trimesh for 3D mesh processing
• FastAPI for the backend framework
• React and Three.js for the frontend

Support

• 📧 Create an issue for bug reports
• 💬 Join our Discord for community support
• 📖 Check the wiki for detailed guides

---

Made with ❤️ for the Roblox creator community