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/cli-tools.md
View on GitHub# CLI Tools Reference
> gltf-transform, gltfpack, Reality Converter — standalone optimization and conversion.
---
## Contents
- gltf-transform
- Inspect a GLB
- Texture Compression (KTX2/Basis)
- meshopt Compression
- Draco Compression
- Full Optimization Pipeline
- Reference Metrics
- Resize Textures
- Dedup (remove duplicate resources)
- gltfpack
- Simplify Mesh
- Simplify to Target
- Generate LODs
- Full Optimization
- Compression Only (no simplification)
- Reality Converter (USDZ — macOS only)
- Usage
- Alternative: usdzconvert (CLI)
- USDZ Constraints
- Comparison: When to Use What
- Before/After Reporting
## gltf-transform
**Install:** `npm install -g @gltf-transform/cli`
**Doc:** https://gltf-transform.dev/cli
### Inspect a GLB
```bash
gltf-transform inspect input.glb
```
Shows: meshes, materials, textures, animations, file size breakdown.
### Texture Compression (KTX2/Basis)
```bash
gltf-transform ktx2 input.glb output.glb --slots "baseColor,normal,occlusion,metallicRoughness,emissive"
```
Reduces texture size 60-80%. GPU-decompressed on client.
### meshopt Compression
```bash
gltf-transform meshopt input.glb output.glb
```
Compresses geometry. No WASM decoder needed client-side (unlike Draco).
### Draco Compression
```bash
gltf-transform draco input.glb output.glb \
--quantize-position 14 \
--quantize-normal 10 \
--quantize-texcoord 12
```
Requires Draco WASM decoder on client (~200KB). More aggressive compression than meshopt.
### Full Optimization Pipeline
> **⚠️ NEVER use `gltf-transform optimize`** — this command includes `simplify` which **destroys mesh geometry** irreversibly. Always use individual steps in order:
```bash
# 1. Resize textures (max 1K for web/mobile)
gltf-transform resize input.glb resized.glb --width 1024 --height 1024
# 2. WebP texture compression (quality 90 preserves detail)
gltf-transform webp resized.glb webp.glb --quality 90
# 3. Draco mesh compression (ALWAYS last — irreversible)
gltf-transform draco webp.glb final.glb
# 4. Inspect the result
gltf-transform inspect final.glb
```
### Reference Metrics
| Step | Typical size | GPU Memory (per texture) |
|---|---|---|
| Raw export (4K textures) | ~22 MB | ~89 MB |
| After 1K resize | ~3.7 MB | ~5.6 MB |
| After WebP q90 | ~3.7 MB | ~5.6 MB |
| After Draco | ~1 MB | ~5.6 MB |
> **16x GPU memory reduction** going from 4K to 1K. Mobile GPUs (Adreno, Mali) benefit the most from texture downscaling.
### Resize Textures
```bash
gltf-transform resize input.glb output.glb --width 1024 --height 1024
```
### Dedup (remove duplicate resources)
```bash
gltf-transform dedup input.glb output.glb
```
---
## gltfpack
**Install:** `npm install -g gltfpack` or binary from https://github.com/zeux/meshoptimizer/releases
**Doc:** https://meshoptimizer.org/gltf/
### Simplify Mesh
```bash
gltfpack -i input.glb -o output.glb -si 0.5
```
`-si 0.5` = simplify to 50% of original faces. Keeps the look, not the topology: it stops
short of the target on a closed mesh, and `-sa` reaches it by opening it (open and
non-manifold edges): never `-sa` on a mesh that ships. For a mesh that must stay closed,
decimate in Blender (Collapse) — `pipeline-import-cleanup.md` § Poly check.
### Simplify to Target
```bash
gltfpack -i input.glb -o output.glb -si 0.5 -sa
```
`-sa` = aggressive simplification (allows topology changes).
### Generate LODs
LODs (Level of Detail) allow the runtime to switch between more or less detailed versions based on camera distance. Uses the `MSFT_lod` extension.
```bash
# Generate 3 LOD levels (100%, 50%, 25% of faces)
gltfpack -i input.glb -o output_lod.glb -si 0.5 -sl 3
```
`-sl 3` = 3 LOD levels. `-si 0.5` = simplification ratio between levels.
**Full LOD workflow (fine control):**
```bash
# 1. LOD0 = original (or slightly optimized)
cp input.glb asset_lod0.glb
# 2. LOD1 = 50% faces
gltfpack -i input.glb -o asset_lod1.glb -si 0.5
# 3. LOD2 = 25% faces
gltfpack -i input.glb -o asset_lod2.glb -si 0.25
# 4. LOD3 = 10% faces (silhouette only)
gltfpack -i input.glb -o asset_lod3.glb -si 0.1 -sa
# 5. Inspect each LOD
gltf-transform inspect asset_lod0.glb
gltf-transform inspect asset_lod1.glb
gltf-transform inspect asset_lod2.glb
gltf-transform inspect asset_lod3.glb
```
**Recommended LOD budget:**
| LOD | Distance | % faces | Usage |
|---|---|---|---|
| LOD0 | 0-10m | 100% | Close-up, hero |
| LOD1 | 10-25m | 50% | Mid-range |
| LOD2 | 25-50m | 25% | Background |
| LOD3 | 50-100m | 10% | Far, silhouette only |
> **⚠️** Always visually check each LOD after generation. `-sa` (aggressive) can create artifacts on marked edges.
### Full Optimization
```bash
gltfpack -i input.glb -o output.glb \
-tc # texture compression (KTX2) \
-tq 8 # texture quality (1-10) \
-si 0.5 # simplify 50%
```
### Compression Only (no simplification)
```bash
gltfpack -i input.glb -o output.glb -cc
```
`-cc` = meshopt compression, no geometry changes.
---
## Reality Converter (USDZ — macOS only)
**Download:** https://developer.apple.com/augmented-reality/tools/
**Type:** GUI application (no CLI)
### Usage
1. Open Reality Converter
2. Drag & drop GLB file
3. Adjust materials if needed
4. File → Export → USDZ
### Alternative: usdzconvert (CLI)
```bash
# Bare pip3 fails on PEP 668 Pythons; use a venv.
python3 -m venv ~/.kiln/venv && ~/.kiln/venv/bin/pip install usd-core
usdzconvert input.glb output.usdz
```
### USDZ Constraints
- Max texture: 4096x4096 (Apple recommends 2048)
- PBR Metallic/Roughness only
- No custom shaders
---
## Comparison: When to Use What
| Need | Tool | Command |
|---|---|---|
| Inspect GLB stats | gltf-transform | `gltf-transform inspect file.glb` |
| Compress textures (KTX2) | gltf-transform | `gltf-transform ktx2 in.glb out.glb` |
| Compress geometry (meshopt) | gltf-transform or gltfpack | `gltf-transform meshopt` or `gltfpack -cc` |
| Compress geometry (Draco) | gltf-transform | `gltf-transform draco in.glb out.glb` |
| Simplify mesh (reduce polys) | gltfpack | `gltfpack -si 0.5` |
| Generate LODs | gltfpack | `gltfpack -si 0.5 -sl 3` |
| Full optimization | gltfpack only | `gltfpack -tc -si 0.5` (⚠️ DO NOT use `gltf-transform optimize`) |
| Resize textures | gltf-transform | `gltf-transform resize --width 1024` |
| Convert to USDZ | usdzconvert | `usdzconvert in.glb out.usdz` |
---
## Before/After Reporting
After any optimization, show:
```
Before: 5.2 MB, 12K faces, 3 textures (2048x2048)
After: 890 KB, 12K faces, 3 textures (1024x1024, KTX2)
Reduction: 83%
Keep this? (yes / no / adjust parameters)
```
Always keep the pre-optimization file as backup.
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 |