elithril/blender-kiln / plugin
kiln
FlaggedMakes and fixes 3D assets in Blender, for games, the web and AR. Use when the user wants a 3D model, prop, character or GLB/glTF/FBX/USDZ file made — from a text brief, a reference image, a free marketplace (PolyHaven, Sketchfab) or AI generation — AND when they bring an existing 3D file to fix: too heavy or too many polygons (optimize, compress, LODs), broken normals, scale or origin, materials lost on glTF export, conversion between GLB, FBX and USDZ, texturing, rigging for animation, animating it (walk and idle cycles, text-to-motion, looping clips, articulated props), or inspection. Drives Blender through a Blender MCP server (ahujasid's or the official Blender Lab one). Batch mode produces many consistent assets unattended. Kiln Studio (`/kiln studio`) opens the project's models in the browser, where the user reviews them and pins notes for Claude to act on.
references/validation-checklist.md
View on GitHub# Validation Checklist Reference
> Systematic QA after import. Execute via `execute_blender_code`.
---
## Contents
- Geometry
- Merge by Distance — and keep the shading
- Recalculate Normals
- Remove Loose
- Degenerate Dissolve
- Check Manifold
- Transforms
- Apply All Transforms
- Set Origin
- Scale Verification
- Naming
- Clean Orphans
- Materials Check
- Material Export Audit (pre-export GLTF)
- Poly Count Check
- Decimate (if needed)
- Execution Order
## Geometry
### Merge by Distance — and keep the shading
Low-poly exports split every edge so each face can carry its own normal. A plain
merge throws those normals away and Blender re-smooths the mesh. Two things fix it:
apply the transforms **first** (the threshold is in the mesh's own units — a cat that
imports at object scale 100 lost 108 of its 928 faces to `0.0001` in local space), and
give every face corner its old normal back after the merge. The merge keeps faces and
their corners in order, so that is a straight copy.
Measured, share of face corners whose normal bends more than 5° off the face (the
look a viewer reads as smooth):
| Mesh | Before | Plain merge | Merge, normals kept |
|---|---:|---:|---:|
| Low-poly cat, 1,856 → 466 vertices | 26.7% | **94.5%** — re-smoothed | **26.7%** (largest change 0.05°) |
| UV sphere with every edge split, 1,104 → 266 | 0.0% | 100.0% | 0.0% |
| Cube, nothing to merge | 0.0% | 0.0% | 0.0% |
The kept normals survive `normals_make_consistent` and a glTF round trip (26.7% after
both). A welded mesh is also what rigging needs — see `references/characters.md`
§ Animation-ready skeleton.
```python
import bpy, bmesh, numpy as np
def weld_keep_shading(obj, dist=1e-4):
"""Rule 10: apply transforms, merge doubles, keep the shading the split edges carried."""
bpy.ops.object.select_all(action='DESELECT'); obj.select_set(True)
bpy.context.view_layer.objects.active = obj
bpy.ops.object.transform_apply(location=True, rotation=True, scale=True)
me = obj.data
corners = np.empty(len(me.loops) * 3)
me.loops.foreach_get("normal", corners)
centres = np.array([p.center[:] for p in me.polygons])
bm = bmesh.new(); bm.from_mesh(me)
before = len(bm.verts)
bmesh.ops.remove_doubles(bm, verts=bm.verts, dist=dist)
merged = before - len(bm.verts)
bm.to_mesh(me); bm.free()
if len(me.polygons) == len(centres) and np.allclose(
centres, [p.center[:] for p in me.polygons], atol=dist * 10):
me.normals_split_custom_set(corners.reshape(-1, 3).tolist())
else: # the merge collapsed a face: say so rather than restore normals onto the wrong corners
print(f"weld: {len(centres) - len(me.polygons)} face(s) collapsed — shading not restored")
return merged # log "{merged} vertices merged"
```
### Recalculate Normals
```python
bpy.ops.object.mode_set(mode='EDIT')
bpy.ops.mesh.select_all(action='SELECT')
bpy.ops.mesh.normals_make_consistent(inside=False)
bpy.ops.object.mode_set(mode='OBJECT')
```
Verify visually: Viewport Overlays → Face Orientation. Blue = correct (outward), Red = flipped.
### Remove Loose
```python
bpy.ops.object.mode_set(mode='EDIT')
bpy.ops.mesh.select_all(action='DESELECT')
bpy.ops.mesh.select_loose()
bpy.ops.mesh.delete(type='VERT')
bpy.ops.object.mode_set(mode='OBJECT')
```
### Degenerate Dissolve
```python
bpy.ops.object.mode_set(mode='EDIT')
bpy.ops.mesh.select_all(action='SELECT')
bpy.ops.mesh.dissolve_degenerate(threshold=0.0001)
bpy.ops.object.mode_set(mode='OBJECT')
```
### Check Manifold
```python
import bmesh
obj = bpy.context.active_object
bm = bmesh.new()
bm.from_mesh(obj.data)
bmesh.ops.remove_doubles(bm, verts=bm.verts[:], dist=1e-5)
# Two different things hide under "non-manifold", and only one is a defect:
fused = [e for e in bm.edges if len(e.link_faces) > 2] # ALWAYS a defect
open_ = [e for e in bm.edges if len(e.link_faces) == 1] # fine on a leaf or a cloth
bm.free()
# Log both counts. fused > 0 → fix before export, in every mode: parts joined
# and welded into internal faces — invisible in renders, and the glTF validator
# passes them.
# open_ > 0 → alert only if the asset must be watertight (3D print, physics).
```
---
## Transforms
### Apply All Transforms
```python
bpy.ops.object.transform_apply(location=True, rotation=True, scale=True)
```
Result: location=(0,0,0), rotation=(0,0,0), scale=(1,1,1).
### Set Origin
```python
# Origin at center of bottom (base of object)
bpy.ops.object.origin_set(type='ORIGIN_GEOMETRY', center='BOUNDS')
# Then adjust to bottom:
obj = bpy.context.active_object
bbox = [obj.matrix_world @ Vector(corner) for corner in obj.bound_box]
min_z = min(v.z for v in bbox)
obj.location.z -= min_z
bpy.ops.object.transform_apply(location=True)
bpy.ops.object.origin_set(type='ORIGIN_GEOMETRY', center='BOUNDS')
```
---
## Scale Verification
**1 Blender unit = 1 meter.** Check bounding box after import:
```python
obj = bpy.context.active_object
dims = obj.dimensions
print(f"Dimensions: {dims.x:.2f} x {dims.y:.2f} x {dims.z:.2f} m")
```
| Object | Expected height |
|---|---|
| Character | ~1.75m |
| Chair | ~0.85m |
| Table | ~0.75m |
| Door | ~2.10m |
Alert if dimensions are clearly wrong (< 0.01m or > 100m).
---
## Naming
Apply naming conventions per `naming-conventions.md`:
```python
# Rename object and mesh data
obj.name = "SM_WoodenChair"
obj.data.name = "SM_WoodenChair_Mesh"
```
### Clean Orphans
```python
# Remove unused data blocks
bpy.ops.outliner.orphans_purge(do_local_ids=True, do_linked_ids=True, do_recursive=True)
```
---
## Materials Check
```python
obj = bpy.context.active_object
# Check for empty material slots
for i, slot in enumerate(obj.material_slots):
if slot.material is None:
print(f"WARNING: Empty material slot at index {i}")
# Check for missing textures
for mat in bpy.data.materials:
if mat.node_tree: # use_nodes goes in 6.0
for node in mat.node_tree.nodes:
if node.type == 'TEX_IMAGE' and node.image is None:
print(f"WARNING: Missing texture in material {mat.name}")
```
---
## Material Export Audit (pre-export GLTF)
**Run BEFORE any GLTF export.** Detects procedural nodes that will be **lost** on export.
```python
import bpy, json
def audit_materials_for_export():
"""Audit materials for GLTF export compatibility. Run before export."""
PROCEDURAL_NODES = {'TEX_NOISE', 'TEX_VORONOI', 'TEX_WAVE', 'TEX_MUSGRAVE'}
results = []
for mat in bpy.data.materials:
if not mat.node_tree: # use_nodes goes in 6.0
continue
info = {"name": mat.name, "warnings": []}
has_principled = False
for node in mat.node_tree.nodes:
if node.type == 'BSDF_PRINCIPLED':
has_principled = True
if node.type in PROCEDURAL_NODES:
info["warnings"].append(
f"Procedural '{node.name}' ({node.type}) → LOST on GLTF export. Bake to texture first."
)
if node.type == 'VALTORGB': # Color Ramp
info["warnings"].append(
f"Color Ramp '{node.name}' → remapping LOST on export. Roughness/metallic will be flat."
)
if node.type == 'TEX_IMAGE' and node.image:
w, h = node.image.size[0], node.image.size[1]
if w > 2048 or h > 2048:
info["warnings"].append(
f"Large texture: {node.image.filepath} ({w}x{h}). Consider resizing to 1024/2048."
)
if not has_principled:
info["warnings"].append("No Principled BSDF → unpredictable export result.")
if info["warnings"]:
results.append(info)
return results
audit = audit_materials_for_export()
if audit:
print("⚠️ MATERIAL PRE-EXPORT AUDIT:")
for mat in audit:
print(f"\n [{mat['name']}]:")
for w in mat["warnings"]:
print(f" - {w}")
else:
print("✅ All materials are GLTF compatible.")
```
**Nodes lost on GLTF export:**
| Blender Node | What is lost | Solution |
|---|---|---|
| Noise/Voronoi/Wave/Musgrave → input | Entire procedural chain | Bake to image texture |
| Color Ramp on roughness/metallic | Value remapping | Bake or manual values |
| Procedural Bump (Noise → Bump) | Bump detail | Bake normal map |
| Mix Shader with complex factor | Blend logic | Simplify to single BSDF |
**What IS exported:** flat roughness/metallic values, image textures (without Color Ramp), baked normal maps, PBR texture sets (baseColor, metallicRoughness, normal).
---
## Poly Count Check
```python
obj = bpy.context.active_object
face_count = len(obj.data.polygons)
# Compare against tier range
# Past 2x the tier's top → propose decimate (ALWAYS interactive); below, report and keep
```
### Decimate (if needed)
```python
mod = obj.modifiers.new(name="Decimate", type='DECIMATE')
mod.decimate_type = 'COLLAPSE'
mod.ratio = target / current # approximate
# SHOW before/after screenshot
# WAIT for user approval before applying
bpy.ops.object.modifier_apply(modifier="Decimate")
```
---
## Execution Order
1. Merge by Distance
2. Recalculate Normals
3. Remove Loose
4. Degenerate Dissolve
5. Check Manifold — fused edges (> 2 faces) must be 0
6. Apply All Transforms
7. Set Origin (center of base)
8. Scale verification
9. Naming conventions
10. Clean orphans
11. Materials check
12. Poly count check → decimate if needed (interactive)
13. `look(mode="angles", target=[name])` → final validation (rule 2)
**Auto mode:** steps 1-11 automatic, step 12 always interactive.
**Print set in CONFIG: steps 1, 4, 5 and 12 change.** The model is at print size, so step 1's
0.1 mm merges real geometry. Measured on a pumpkin built closed by exact unions: exported as
built, `print_check` PASS (0 non-manifold); after step 1 alone, FAIL (3 edges shared by more
than two faces) — while step 5's count still read 0 on the merged mesh. So:
- **steps 1 and 4 are skipped** for a model built closed by `print.md` § Printable from the
brief; on a mesh being repaired, merge at 1e-6 m (0.001 mm), never more;
- **step 5 is `tools/print_check.py` on the exported STL**, before and after any cleanup step:
a step that turns PASS into FAIL is undone, and logged;
- **step 12 does not apply** — the detail tier is a screen budget; a print is not decimated
to fit it, only to keep a voxel remesh sliceable (`print.md` rule 3, remesh last).
**Guided mode:** validate after each step.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |