Blender Mastery — AdamoBot's 3D Powerhouse

---
name: blender
description: Headless Blender automation for 3D asset pipelines, including FBX/GLB conversion, model inspection, optimization, rendering, procedural scene generation, terrain/environment generation, and bpy scripting. Use this skill whenever the user mentions Blender, headless Blender, bpy, FBX to GLB, GLB inspection, 3D asset conversion, Blender rendering, Blender MCP, or procedural 3D generation.
---

# Blender Mastery — AdamoBot's 3D Powerhouse

Blender 5.1.0 headless automation via the bundled `bpy` API. Everything runs without a GUI.

This is the canonical ForgeBot Blender skill. It was promoted from the former nested model-generation subskill; keep Blender-specific plans, references, tests, and assets here.

## Current Capabilities (Shipped)

| Script | What It Does |
|--------|-------------|
| `blender-smoke-test.py` | Verify Blender pipeline is healthy |
| `blender-fbx-to-glb.py` | FBX → GLB conversion with structured error reporting |
| `blender-inspect-model.py` | Query any model for verts, faces, materials, bones, bounding box |
| `blender-batch-convert.py` | Batch FBX → GLB with incremental skip and manifest output |

All at `~/forgeapps/apps/jd/scripts/`.

## Invocation

```bash
source ~/.bashrc
blender --background --python <script.py> -- <args>
```

## Slash Commands

| Command | What it does |
|---------|--------------|
| `/blender selftest` | Runs `.claude/skills/blender/scripts/selftest.ts`, creates a random `.blend` scene with exactly three random primitives and three random colors, then opens it in Blender on this Mac |

---

## Bundled Support Files

Load these only when the task needs them:

| Folder | Use |
|--------|-----|
| `scripts/` | TypeScript automation entry points, including `/blender selftest` |
| `plans/` | Roadmaps and PRDs for asset conversion, construction-site scene generation, terrain generation, and environment tooling |
| `references/` | Research on Blender-native and MCP-driven outdoor scene generation workflows |
| `__tests__/` | TypeScript coverage for the Blender generator backlog and local Blender installation |
| `assets/` | Reference imagery used by Blender scene/environment plans |

## Plans & Roadmaps

Detailed plans live in `plans/`:

| Plan | What |
|------|------|
| [MASTER-PLAN.md](plans/MASTER-PLAN.md) | Original master plan |
| [asset-pipeline-roadmap.md](plans/asset-pipeline-roadmap.md) | 20 asset pipeline scripts across 4 tiers |
| [construction-sim-environment.md](plans/construction-sim-environment.md) | 20 environment design scripts (terrain, props, scenarios) |

## Environment

- **Blender:** 5.1.0 at `C:\Program Files\Blender Foundation\Blender 5.1\`
- **Shell:** `blender` function in `~/.bashrc`
- **Python:** Bundled 3.13 (use only via `blender --background --python`)
- **Scripts home:** `~/forgeapps/apps/jd/scripts/`
- **Model assets:** `~/forgeapps/apps/jd/models/` (15 subdirs, ~977 MB, 237 FBX files)
- **blender-mcp:** Installed (`pip install git+https://github.com/ahujasid/blender-mcp.git`). MCP bridge for LLM→Blender control — scene inspection, object/material ops, Python execution, Poly Haven/Sketchfab asset integration.

## References

| Reference | What |
|-----------|------|
| [AI Outdoor Scene Gen Research](references/Small-Scale%20AI%20Generation%20of%203D%20Outdoor%20Game%20Environments%20for%20Blender-deep-research-report.md) | Deep research on best approaches: MCP pipelines, Infinigen, StableGen, Poly Haven, BlenderProc |

## Key Lessons (from TERRAFORMER)

- **Volume Scatter kills renders.** Even density 0.0002 across a 600m scene produces black output. Use post-process color grading for atmospheric haze instead.
- **sRGB→Linear conversion** is critical. Principled BSDF expects linear values: `linear = srgb ** 2.2`.
- **mathutils.noise** for procedural generation in headless mode — shader nodes don't work without a renderer.
- **Texture UV mapping:** Use planar projection with TexCoord→Mapping→TexImage chain. Tiling via Mapping node Scale input.