Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
Fix palette snapping for render previews
Matt Kissingerda2fd3adc27e
diff --git a/src/__tests__/scene-palette.test.ts b/src/__tests__/scene-palette.test.tsindex ac0eb456..034b7b6f 100644--- a/src/__tests__/scene-palette.test.ts+++ b/src/__tests__/scene-palette.test.ts@@ -22,7 +22,12 @@ import {} from '../render';import { collectGlbMetrics } from '../metrics';import { hexToLinearRgb, buildSlotIndex, chooseSlot } from '../palette-snap';-import { renderPaletteDirective, OPTIMIZED_PALETTE } from '../palette';+import {+ renderPaletteDirective,+ OPTIMIZED_PALETTE,+ GENERAL_RENDER_PALETTE,+ paletteToSnapSlots,+} from '../palette';const hue = (i: number, n: number): number => new THREE.Color().setHSL(i / n, 0.7, 0.5).getHex();@@ -84,6 +89,20 @@ describe('palette-snap (pure)', () => {expect(chooseSlot(idx, { baseLinear: [0.5, 0.6, 0.7], transparent: true })).toBe(1);expect(chooseSlot(idx, { baseLinear: [0.05, 0.05, 0.05] })).toBe(0); // opaque fallback});++ it('general render palette keeps dark foliage green and bark brown', () => {+ const slots = paletteToSnapSlots(GENERAL_RENDER_PALETTE);+ const idx = buildSlotIndex(slots);+ const pickName = (hex: string): string | undefined => {+ const slotI = chooseSlot(idx, { baseLinear: hexToLinearRgb(hex) });+ return slotI === undefined ? undefined : GENERAL_RENDER_PALETTE[slotI]?.name;+ };++ expect(pickName('#2d5a27')).toBe('leaf-dark');+ expect(pickName('#35503a')).toBe('leaf-dark');+ expect(pickName('#556b2f')).toBe('leaf-olive');+ expect(pickName('#4a3424')).toBe('bark');+ });});describe('snapGlbToPalette', () => {diff --git a/src/palette-snap.ts b/src/palette-snap.tsindex c4d4008c..81ca9a58 100644--- a/src/palette-snap.ts+++ b/src/palette-snap.ts@@ -24,8 +24,16 @@ export interface SnapSlot {color: string;/** Defaults to 'opaque'. transparent→glass, emissive→glow. */kind?: SnapSlotKind;+ /** Optional PBR values applied by material-bake callers. */+ metalness?: number;+ roughness?: number;+ /** Opacity for glass slots. */+ opacity?: number;}+/** Public palette slot shape shared by GLB snapping and CPU preview snapping. */+export type SnapPaletteSlot = SnapSlot;+export type Vec3 = [number, number, number];// ── sRGB → linear. Matches three's SRGBToLinear (the gamma transfer function),diff --git a/src/palette.ts b/src/palette.tsindex c4fda6e9..e9a5e146 100644--- a/src/palette.ts+++ b/src/palette.ts@@ -19,6 +19,8 @@* never drift.*/+import type { SnapPaletteSlot } from './palette-snap';+/** One material role in the canonical palette. A PBR spec the directive names and* a future shared palette texture bakes from. */export interface PaletteSlot {@@ -43,7 +45,7 @@ export interface PaletteSlot {}/**- * The canonical 19-slot palette covering war / city / fantasy / sci-fi / organic /+ * The canonical 22-slot palette covering war / city / fantasy / sci-fi / organic /* character domains. Stable order; values are tunable. `glass` is the only* transparent slot and `glow` the only emissive — keeping the alpha-mode story* simple (opaque everything + the one glass slot).@@ -204,8 +206,52 @@ export const OPTIMIZED_PALETTE: readonly PaletteSlot[] = [emissive: true,use: 'lamps, neon, fire cores, vfx — the ONE emissive slot',},+ {+ index: 19,+ name: 'leaf-dark',+ color: '#2f5a2a',+ metalness: 0.0,+ roughness: 0.9,+ use: 'dark evergreen leaves, shadowed foliage, conifers',+ },+ {+ index: 20,+ name: 'leaf-olive',+ color: '#586a30',+ metalness: 0.0,+ roughness: 0.9,+ use: 'olive foliage, dry leaves, canvas greens',+ },+ {+ index: 21,+ name: 'bark',+ color: '#46301f',+ metalness: 0.0,+ roughness: 0.85,+ use: 'tree bark, dark roots, rough brown wood',+ },];+/**+ * Default snap target for optimized/theme render policy. It aliases the canonical+ * optimized palette so GLBs and CPU previews share one material-color contract when+ * a caller explicitly chooses palette coherence over faithful source colors.+ */+export const GENERAL_RENDER_PALETTE: readonly PaletteSlot[] = OPTIMIZED_PALETTE;++/** Convert authoring palette slots into the snap shape used by GLB + CPU preview bakes. */+export function paletteToSnapSlots(+ slots: readonly PaletteSlot[] = GENERAL_RENDER_PALETTE,+): SnapPaletteSlot[] {+ return slots.map((s) => ({+ color: s.color,+ kind: s.transparent ? 'glass' : s.emissive ? 'glow' : 'opaque',+ metalness: s.metalness,+ roughness: s.roughness,+ ...(s.opacity !== undefined ? { opacity: s.opacity } : {}),+ }));+}+/*** Render the authoring directive appended to the agent prompt when the* "Optimized palette" toggle is on (or a custom scene palette is chosen). Natural-diff --git a/src/render.ts b/src/render.tsindex fe6818aa..d596190e 100644--- a/src/render.ts+++ b/src/render.ts@@ -24,7 +24,13 @@ import {mergeDocuments,} from '@gltf-transform/functions';-import { buildSlotIndex, chooseSlot, hexToLinearRgb, type SnapSlot } from './palette-snap';+import {+ buildSlotIndex,+ chooseSlot,+ hexToLinearRgb,+ type SnapSlot,+ type SnapPaletteSlot,+} from './palette-snap';import { buildSandboxGlobals, countTriangles } from './primitives';import {@@ -77,6 +83,7 @@ const TYPE_VEC4: AccessorTypeStr = 'VEC4';* from GLB bytes, so it travels in provenance. See plan/05-product-depth.md §3.4.*/export type AssetRole = 'ground' | 'building' | 'wonder' | 'poi' | 'prop' | 'fill' | 'vehicle';+export type { SnapPaletteSlot } from './palette-snap';export interface KilnCodeMeta {name?: string;@@ -983,18 +990,6 @@ export async function optimizeGlbBytes(// Palette snap (scene palettes) — web-side hard snap to a user-defined palette// =============================================================================-/** One slot the GLB snap targets: a color + kind + optional PBR/opacity. */-export interface SnapPaletteSlot {- /** sRGB hex (e.g. `#9fc9a3`). */- color: string;- /** Defaults to 'opaque'. transparent material → glass, emissive → glow. */- kind?: 'opaque' | 'glass' | 'glow';- metalness?: number;- roughness?: number;- /** Opacity for a glass slot (default 0.4). */- opacity?: number;-}-/** Result of {@link snapGlbToPalette}. */export interface SnapGlbResult {/** The snapped + consolidated GLB bytes. */diff --git a/src/views/__tests__/views.test.ts b/src/views/__tests__/views.test.tsindex 7c498cf3..02c3bcd9 100644--- a/src/views/__tests__/views.test.ts+++ b/src/views/__tests__/views.test.ts@@ -8,9 +8,12 @@ import {renderInteriorGrid,hideNodeInScene,SIX_VIEWS,+ snapSceneToPalette,} from '../index';import { encodePng } from '../png';import { executeKilnCode } from '../../render';+import { GENERAL_RENDER_PALETTE, paletteToSnapSlots } from '../../palette';+import { hexToLinearRgb } from '../../palette-snap';const BOX_CODE = `const meta = { name: 'test-box', category: 'prop' };@@ -21,6 +24,15 @@ function build() {}`;+const DARK_FOLIAGE_CODE = `+const meta = { name: 'dark-foliage', category: 'environment' };+function build() {+ const root = createRoot('Root');+ createPart('Mesh_Leaf', boxGeo(1, 1, 1), gameMaterial('#2d5a27'), { parent: root, position: [0, 0.5, 0] });+ return root;+}+`;+// Elongated along +X (correct kiln frame for a "forward" asset).const LONG_X_CODE = `const meta = { name: 'long-x', category: 'prop' };@@ -159,6 +171,29 @@ describe('renderViewGrid / renderCodeViewGrid', () => {const result = await renderViewGrid(root, { size: 32 });expect(result.png.length).toBeGreaterThan(100);});++ test('snapSceneToPalette applies the general render palette before CPU previews', async () => {+ const { root } = await executeKilnCode(DARK_FOLIAGE_CODE);+ const snap = snapSceneToPalette(root, paletteToSnapSlots(GENERAL_RENDER_PALETTE));+ expect(snap.snapped).toBe(1);+ expect(snap.skipped).toBe(0);++ let color: { r: number; g: number; b: number } | undefined;+ (+ root as {+ traverse: (+ cb: (obj: { isMesh?: boolean; material?: { color?: typeof color } }) => void,+ ) => void;+ }+ ).traverse((obj) => {+ if (obj.isMesh && obj.material?.color) color = obj.material.color;+ });++ const expected = hexToLinearRgb('#2f5a2a');+ expect(color?.r).toBeCloseTo(expected[0], 5);+ expect(color?.g).toBeCloseTo(expected[1], 5);+ expect(color?.b).toBeCloseTo(expected[2], 5);+ });});// A roof group (named 'Roof') of child meshes — the rasterizer culls per-mesh, sodiff --git a/src/views/index.ts b/src/views/index.tsindex 4e94ec05..54b0dd4f 100644--- a/src/views/index.ts+++ b/src/views/index.ts@@ -29,6 +29,13 @@ import {stampLabel,type DuckClip,} from './pose';+import {+ buildSlotIndex,+ chooseSlot,+ hexToLinearRgb,+ type SnapPaletteSlot,+ type Vec3,+} from '../palette-snap';export { rasterizeView, measureBounds, hideNodeInScene, SIX_VIEWS, coverage } from './raster';export type { RasterOptions, ViewSpec } from './raster';@@ -48,6 +55,120 @@ export {const PAD = 4;const PAD_COLOR: [number, number, number] = [10, 11, 13];+interface DuckColor {+ r: number;+ g: number;+ b: number;+}++interface DuckMaterial {+ color?: DuckColor;+ emissive?: DuckColor;+ emissiveIntensity?: number;+ transparent?: boolean;+ opacity?: number;+ metalness?: number;+ roughness?: number;+ map?: unknown;+ vertexColors?: boolean;+}++interface DuckMesh {+ isMesh?: boolean;+ material?: DuckMaterial | DuckMaterial[];+}++interface DuckObject3D {+ traverse?: (cb: (obj: DuckMesh) => void) => void;+}++export interface ScenePaletteSnapResult {+ snapped: number;+ skipped: number;+}++function setLinearColor(color: DuckColor | undefined, rgb: Vec3): void {+ if (!color) return;+ color.r = rgb[0];+ color.g = rgb[1];+ color.b = rgb[2];+}++function snapMaterialToPalette(+ mat: DuckMaterial,+ slots: readonly SnapPaletteSlot[],+ idx: ReturnType<typeof buildSlotIndex>,+): boolean | undefined {+ if (!mat.color) return undefined;+ if (mat.map || mat.vertexColors) return false;++ const emissive =+ mat.emissive && (mat.emissiveIntensity ?? 1) > 0+ ? ([+ mat.emissive.r * (mat.emissiveIntensity ?? 1),+ mat.emissive.g * (mat.emissiveIntensity ?? 1),+ mat.emissive.b * (mat.emissiveIntensity ?? 1),+ ] as Vec3)+ : undefined;+ const slotI = chooseSlot(idx, {+ baseLinear: [mat.color.r, mat.color.g, mat.color.b],+ ...(emissive ? { emissiveLinear: emissive } : {}),+ transparent: mat.transparent === true || (mat.opacity !== undefined && mat.opacity < 0.98),+ });+ if (slotI === undefined) return false;++ const slot = slots[slotI]!;+ const kind = slot.kind ?? 'opaque';+ const rgb = hexToLinearRgb(slot.color);+ setLinearColor(mat.color, rgb);+ if (mat.metalness !== undefined) mat.metalness = slot.metalness ?? 0;+ if (mat.roughness !== undefined)+ mat.roughness = slot.roughness ?? (kind === 'glass' ? 0.1 : 0.85);++ if (kind === 'glass') {+ mat.transparent = true;+ mat.opacity = slot.opacity ?? 0.4;+ } else {+ if (mat.transparent !== undefined) mat.transparent = false;+ if (mat.opacity !== undefined) mat.opacity = 1;+ }++ if (mat.emissive) {+ if (kind === 'glow') {+ setLinearColor(mat.emissive, rgb);+ mat.emissiveIntensity = Math.max(mat.emissiveIntensity ?? 1, 1);+ } else {+ setLinearColor(mat.emissive, [0, 0, 0]);+ if (mat.emissiveIntensity !== undefined) mat.emissiveIntensity = 0;+ }+ }+ return true;+}++/** Snap flat-color scene materials to a palette before CPU preview rasterization. */+export function snapSceneToPalette(+ root: unknown,+ slots: readonly SnapPaletteSlot[],+): ScenePaletteSnapResult {+ if (slots.length === 0) return { snapped: 0, skipped: 0 };+ const traverse = (root as DuckObject3D | undefined)?.traverse;+ if (!traverse) return { snapped: 0, skipped: 0 };++ const idx = buildSlotIndex(slots);+ let snapped = 0;+ let skipped = 0;+ traverse.call(root, (obj: DuckMesh) => {+ if (!obj.isMesh || !obj.material) return;+ const materials = Array.isArray(obj.material) ? obj.material : [obj.material];+ for (const mat of materials) {+ const didSnap = snapMaterialToPalette(mat, slots, idx);+ if (didSnap === true) snapped++;+ else if (didSnap === false) skipped++;+ }+ });+ return { snapped, skipped };+}+export interface ViewGridResult {png: Buffer;width: number;@@ -58,6 +179,8 @@ export interface ViewGridResult {export interface ViewGridOptions extends RasterOptions {views?: ViewSpec[];+ /** Snap flat-color materials before rasterization. Mutates the provided scene root. */+ snapPalette?: readonly SnapPaletteSlot[];}/** Render a (possibly sandbox-created) Three.js scene root into the 3x2 grid. */@@ -67,6 +190,7 @@ export async function renderViewGrid(): Promise<ViewGridResult> {const size = opts.size ?? 256;const views = opts.views ?? SIX_VIEWS;+ if (opts.snapPalette?.length) snapSceneToPalette(root, opts.snapPalette);const cols = 3;const rows = Math.ceil(views.length / cols);const width = cols * size + (cols + 1) * PAD;