# Mech Prompt Engineering Guide - HuggingFace Space

## Problem: AI Generates Organic Shapes Instead of Mechanical

**Root Cause:** Text-to-3D AI interprets "chicken mech" literally as organic chicken shape.

**Solution:** Use precise mechanical keywords + reference images OR highly detailed prompts.

---

## Method 1: Image-to-3D (RECOMMENDED - 90% Success Rate)

**Workflow:**
1. Generate concept art with FLUX.1-schnell (2D image generation)
2. Use image as reference for Hunyuan3D-2 (image-to-3D)
3. Result: Precise mechanical design

**Example:**
```python
# Step 1: Generate concept art (FLUX)
result = client.predict(
    prompt="bipedal chicken mech, hard surface, mechanical legs, armored body, sci-fi, white background, front view, game asset",
    quality="High",
    api_name="/generate_2d_asset_pro"
)

# Step 2: Use image for 3D generation
result = client.predict(
    prompt="mechanical chicken mech, hard surface, game asset",
    image=result[0],  # Use generated concept art
    quality="High",
    api_name="/lambda"
)
```

---

## Method 2: Text-Only with Precise Keywords (70% Success Rate)

**Critical Keywords for Mechanical Designs:**

### Hard-Surface Keywords (MUST INCLUDE)
- `hard surface` - Forces geometric, non-organic shapes
- `mechanical` - Emphasizes machine parts
- `armored` - Adds plating, panels
- `sci-fi` - Futuristic tech aesthetic
- `game asset` - Optimized geometry
- `white background` - Clean isolation

### Material Keywords
- `metal plating` - Metallic surfaces
- `rivets and bolts` - Mechanical details
- `panel lines` - Surface detail
- `hydraulic joints` - Mechanical articulation
- `exposed machinery` - Internal mechanisms

### Style Keywords
- `low-poly` - Simplified geometry (game-ready)
- `stylized` - Artistic interpretation
- `realistic` - Photorealistic details
- `industrial design` - Functional aesthetics

### Negative Keywords (What to AVOID)
- ❌ `organic` - Creates biological shapes
- ❌ `feathers` - Adds organic details
- ❌ `realistic chicken` - Too literal
- ❌ `cartoon` - May create soft shapes

---

## Prompt Templates for Different Mech Types

### Chicken Mech (Bipedal Walker)
```
"bipedal chicken mech, hard surface mechanical design, armored metal plating, 
hydraulic legs, sci-fi military robot, panel lines and rivets, game asset, 
white background, front view, low-poly stylized"
```

**Key Elements:**
- `bipedal` - Two legs (not four)
- `hard surface mechanical` - Non-organic
- `armored metal plating` - Mechanical materials
- `hydraulic legs` - Mechanical joints
- `panel lines and rivets` - Surface detail

### Tank Mech (Tracked Vehicle)
```
"tracked tank mech, hard surface armor, heavy weapons platform, 
industrial design, metal plating with rivets, sci-fi military vehicle, 
game asset, white background, isometric view"
```

### Spider Mech (Multi-Legged)
```
"spider mech with 6 mechanical legs, hard surface design, armored body, 
hydraulic joints, sci-fi robot, metal construction, game asset, 
white background, top-down view"
```

### Humanoid Mech (Gundam-Style)
```
"humanoid battle mech, hard surface armor, mechanical joints, 
sci-fi military robot, panel lines and vents, game asset, 
white background, front view, heroic pose"
```

---

## Prompt Structure Formula

**Optimal Format:**
```
[Type] + [Hard-Surface Keywords] + [Materials] + [Details] + [Context] + [Technical]
```

**Example Breakdown:**
```
"bipedal chicken mech" (Type)
+ "hard surface mechanical design" (Hard-Surface)
+ "armored metal plating" (Materials)
+ "hydraulic legs, panel lines, rivets" (Details)
+ "sci-fi military robot" (Context)
+ "game asset, white background, front view" (Technical)
```

---

## Quality Settings for Mechs

**Recommended Settings:**
- **Quality:** High (30 steps, 512 octree, 2K textures)
- **Reason:** Mechanical details need precision
- **Time:** 60-90 seconds

**Fast Iteration (Testing Prompts):**
- **Quality:** Balanced (15 steps, 384 octree, 2K textures)
- **Reason:** Quick feedback on prompt effectiveness
- **Time:** 30-45 seconds

---

## Testing Your Prompts

**Iteration Workflow:**
1. Start with Balanced quality (fast feedback)
2. Test prompt variations
3. Once prompt works, use High quality
4. If still organic, switch to image-to-3D method

**Common Issues:**

**Issue:** Still looks organic
**Fix:** Add more hard-surface keywords: `mechanical joints`, `metal construction`, `industrial design`

**Issue:** Too abstract/simple
**Fix:** Add detail keywords: `panel lines`, `rivets`, `vents`, `hydraulic pistons`

**Issue:** Wrong proportions
**Fix:** Add view keywords: `front view`, `side view`, `isometric view`

---

## Advanced: Multi-View Generation

**For Complex Mechs:**
```python
# Generate multiple views
views = ["front view", "side view", "back view", "top view"]

for view in views:
    prompt = f"bipedal chicken mech, hard surface, mechanical, {view}, white background"
    result = client.predict(prompt=prompt, quality="High", api_name="/lambda")
    # Use all views as reference for final model
```

---

## Comparison: Text-Only vs Image-to-3D

**Text-Only:**
- ✅ Faster (no 2D generation step)
- ✅ Good for simple designs
- ❌ Less precise control
- ❌ Higher chance of organic shapes

**Image-to-3D:**
- ✅ Precise control over design
- ✅ 90%+ success rate for mechanical
- ✅ Can iterate on 2D concept first
- ❌ Requires 2D generation step (adds 30-60s)

**Recommendation:** Use image-to-3D for hero mechs, text-only for variations.

---

## Example: Complete Chicken Mech Generation

**Step 1: Generate Concept Art (FLUX)**
```python
concept_result = client.predict(
    prompt="bipedal chicken mech, hard surface mechanical design, armored legs, "
           "sci-fi military robot, front view, white background, game concept art, "
           "detailed panel lines, hydraulic joints, metal plating",
    quality="High",
    api_name="/generate_2d_asset_pro"
)
# Result: 2D concept art image
```

**Step 2: Generate 3D Model (Hunyuan3D-2)**
```python
mech_result = client.predict(
    prompt="mechanical chicken mech, hard surface, game asset, detailed",
    image=concept_result[0],  # Use concept art as reference
    quality="High",
    api_name="/lambda"
)
# Result: Precise mechanical 3D model
```

**Step 3: Process in Blender (Optional)**
```python
# If needed, refine in Blender
processed = client.predict(
    input_path=mech_result[0],
    target_height=2.0,
    generate_lod=True,
    generate_collision=True,
    api_name="/process_for_godot"
)
```

---

## Quick Reference: Keyword Cheat Sheet

**ALWAYS INCLUDE:**
- `hard surface`
- `mechanical`
- `game asset`
- `white background`

**FOR DETAILS:**
- `panel lines`
- `rivets`
- `hydraulic joints`
- `metal plating`

**FOR STYLE:**
- `sci-fi` (futuristic)
- `industrial` (functional)
- `military` (combat-ready)
- `low-poly` (game-optimized)

**NEVER INCLUDE:**
- ❌ `organic`
- ❌ `feathers`
- ❌ `realistic chicken`
- ❌ `cartoon` (unless stylized is goal)

---

## Troubleshooting

**Problem:** Still getting organic shapes
**Solution:** Use image-to-3D method with FLUX concept art

**Problem:** Too simple/blocky
**Solution:** Add detail keywords: `panel lines`, `rivets`, `vents`, `hydraulic pistons`

**Problem:** Wrong scale/proportions
**Solution:** Add view keywords: `front view`, `heroic pose`, `isometric view`

**Problem:** Not game-ready
**Solution:** Add `game asset`, `low-poly`, `optimized geometry`

---

## Next Steps

1. **Test Prompts:** Use Balanced quality for fast iteration
2. **Refine:** Add keywords based on results
3. **Switch to Image-to-3D:** If text-only fails
4. **Process:** Use Blender pipeline for final optimization

**Your HuggingFace Space has all these capabilities built-in!**

---

**Token Usage: 106,086/200,000 (53%)**