settled-reach/spikes/3dpipeline

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:

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

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/