# 3D Pipeline Spike

Proof of concept for the Trellis image-to-3D asset pipeline with runtime
recoloring in Godot 4.6.

## What This Proves

1. **Trellis generates usable 3D assets** from 2D concept art (via /image-gen)
2. **Blender post-processing** normalizes scale, centers models, generates
   recolor masks, and adjusts materials for toon rendering
3. **Godot renders textured GLBs** with embedded textures when
   `gltf/embedded_image_handling=3` (embed uncompressed) is set
4. **Luminance-preserving recoloring** via shader + mask sidecar: tint the
   dominant color region while keeping texture detail (shadows, highlights,
   edges)

## Pipeline

```
concept.png ──→ Trellis ──→ raw.glb ──→ Blender postprocess ──→ model.glb + mask.png
                                                                      │
                                                               Godot import
                                                               (embedded textures)
                                                                      │
                                                               toon_masked.gdshader
                                                               (texture + mask + tint)
```

## Key Findings

### GLB Import Settings (Critical)

Godot's GLTF importer `gltf/embedded_image_handling` values:

| Value | Mode | Result |
|-------|------|--------|
| 0 | Discard textures | Models render without any texture |
| 1 | Extract textures | **Silently fails** — materials get null texture refs |
| 2 | Embed as Basis Universal | Compressed, may lose quality |
| 3 | Embed uncompressed | **Works correctly** — textures preserved in .scn |

**Always use value 3** for Trellis-generated GLBs. Set in project.godot under
`[gltf]` so new imports pick it up automatically.

### Recolor Shader

The `toon_masked.gdshader` uses luminance-preserving blending:

```glsl
float luma = dot(original.rgb, vec3(0.299, 0.587, 0.114));
vec3 tinted = tint_color.rgb * (luma * 1.5 + 0.2);
vec3 base = mix(original.rgb, tinted, mask);
```

- Where `mask = 0` (black): original Trellis texture preserved
- Where `mask = 1` (white): tint color applied, scaled by original luminance
- This keeps shadows, highlights, and detail lines even in recolored regions

The mask default is `hint_default_black` (replace nothing when no mask loaded).

### Toon Shadow

Gentle 15% darkening with `smoothstep` transition — not the harsh binary
shadow/lit split. This preserves texture readability at isometric camera angles
where many faces would otherwise be fully in shadow.

### Alpha / See-Through Fix

Trellis texture atlases sometimes have alpha artifacts at UV seams. The shader
does NOT output ALPHA — all models render fully opaque. If transparency is
needed for specific assets (glass, holograms), use a separate shader variant.

## Running

```bash
cd spikes/3dpipeline
godot --headless --import   # first time only — generates .godot/imported/
godot --path .              # run the spike
```

### Controls

| Key | Action |
|-----|--------|
| WASD | Pan camera (screen-aligned) |
| Mouse wheel | Zoom in/out |
| T | Cycle camera angle (top-down / 45 iso / 30 dramatic) |
| R | Randomize character colors |

## Files

```
project.godot                          # Minimal Godot project config
scenes/spike_3d.tscn                   # Main scene (Camera3D + script)
scripts/spike/spike_main.gd            # Camera, model loading, shader application
shaders/spike/toon_masked.gdshader     # Texture + recolor mask + toon shadow
shaders/spike/toon.gdshader            # Flat color toon (characters)
shaders/spike/outline.gdshader         # Inverted hull outline (not used yet)
models/furniture/*.glb + *_mask.png    # Post-processed Trellis models + masks
models/props/*.glb + *_mask.png        # Post-processed Trellis props + masks
```

## Known Issues

- Baroque table mask is too aggressive — tints the whole model bright white
- Character scale needs tuning relative to furniture
- Trellis mesh quality varies — some models have holes visible at close zoom
- No outline shader applied yet (inverted hull ready but not wired up)

## Dependencies

- Godot 4.6+ (gl_compatibility renderer)
- Models generated by: `tooling/db/trellis_connector.py` + `.claude/skills/glb-gen/`
- Concept images generated by: `.claude/skills/image-gen/`