# Contributing to the Blender Script Repository
## 🚀 Quick Start
1. **Generate Script**: Ask Gemini (or other AI) to create a Blender Python script
2. **Test Locally**: Run the script in Blender to verify it works
3. **Add to Repository**: Follow the steps below
## 📝 Adding a New Script
### 1. Choose Category
- `robots/` - Robot models, drones, manipulators
- `architecture/` - Buildings, castles, structures
- `tools/` - Utilities, generators, modifiers
- `environments/` - Terrain, vegetation, weather systems
### 2. Create Script File
```bash
# File: scripts/[category]/[script_name].py
# Example: scripts/architecture/hohensalzburg_fortress.py
```
### 3. Script Format Requirements
```python
"""
[Script Title]
Generated by [AI Model]
[Detailed description of what the script creates]
Author: [AI Model or Human]
Category: [robots|architecture|tools|environments]
Tags: [tag1, tag2, tag3]
Dimensions: [physical dimensions if applicable]
Complexity: [simple|medium|complex]
"""
import bpy
# ... script code ...
```
### 4. Update Index
Edit `scripts/index.json` and add your script to the appropriate category:
```json
"[script_name]": {
"name": "[Display Name]",
"description": "[Brief description]",
"file": "[category]/[script_name].py",
"author": "[AI Model]",
"tags": ["tag1", "tag2"],
"dimensions": "[size info]",
"complexity": "medium",
"features": ["feature1", "feature2"],
"parameters": {},
"created": "2026-01-19",
"last_updated": "2026-01-19"
}
```
### 5. Update Metadata
Increment `total_scripts` count in the metadata section.
### 6. Test with MCP
```python
# List all scripts
await robot_model(operation="list_scripts")
# Execute your script
await robot_model(
operation="execute_repository_script",
category="architecture",
script_name="your_script_name",
output_path="D:/models/output.fbx"
)
```
## 🎯 Script Quality Guidelines
### ✅ Must Have
- Comprehensive docstring with all metadata fields
- Clear, commented code
- Proper object naming in Blender
- Error-free execution in Blender 3.0+
### ✅ Should Have
- Parameterized dimensions where applicable
- Realistic scaling
- Proper materials/textures when relevant
- Performance considerations for complex models
### 🚫 Avoid
- Hardcoded file paths
- Platform-specific code
- Unnecessary complexity
- Missing error handling
## 🤖 AI Script Generation Tips
### Effective Prompts
```
"Create a Blender Python script to generate a detailed 3D model of [object].
Include proper scaling, materials, and make it production-ready.
Use clear variable names and add comments explaining complex sections."
```
### Common Issues to Check
- **Scaling**: Ensure realistic dimensions (meters)
- **Materials**: Add basic materials for better visualization
- **Performance**: Avoid excessive geometry for complex models
- **Naming**: Use consistent naming conventions
## 🔧 Development Workflow
1. **Generate** → AI creates script
2. **Test** → Run in Blender locally
3. **Refine** → Fix any issues
4. **Document** → Add proper docstring
5. **Integrate** → Add to repository and index
6. **Test MCP** → Verify works with robotics-mcp
7. **Submit** → Create PR or commit
## 📊 Repository Stats
- **Total Scripts**: 13 (robots: 10, architecture: 3)
- **AI Models**: Gemini, Grok
- **Contributors**: Gemini AI, Grok AI
- **Last Updated**: 2026-01-19
The repository grows with every contribution, building an amazing library of AI-generated 3D modeling scripts! 🎨🤖
