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
/** Three state and affine UV wrapper; host resources never enter authored arguments. */
import * as THREE from 'three';
import { applyPortableSamplerV1 } from './portable-sampler-runtime';
import {
compileTextureAtlasSpecV1,
type TextureAtlasCompileOptionsV1,
type TextureAtlasManifestV1,
} from './texture-atlas-pixels';
import {
atlasFailure,
canonicalAtlasMetadataJsonV1,
TEXTURE_ATLAS_COMPILER_IDS,
TEXTURE_ATLAS_COMPILER_ID_V1_2,
TEXTURE_ATLAS_LIMITS,
TEXTURE_ATLAS_LIMITS_V1_2,
} from './texture-atlas-contract';
import { sha256Hex } from './procedural-material-v2';
import { remapUV } from './uv-shapes';
/** SDK/host API. Sandbox integration closes over options and exposes exactly one argument. */
export async function textureAtlas(
input: unknown,
options: TextureAtlasCompileOptionsV1 = {},
): Promise<THREE.DataTexture> {
const compiled = await compileTextureAtlasSpecV1(input, options);
const texture = new THREE.DataTexture(
compiled.pixels,
compiled.spec.width,
compiled.spec.height,
THREE.RGBAFormat,
THREE.UnsignedByteType,
);
texture.name = 'Atlas';
texture.flipY = false;
texture.colorSpace =
compiled.spec.usage === 'albedo' || compiled.spec.usage === 'emissive'
? THREE.SRGBColorSpace
: THREE.NoColorSpace;
applyPortableSamplerV1(texture, compiled.spec.sampler);
texture.userData.kilnAtlas = { spec: compiled.spec, manifest: compiled.manifest };
texture.userData.kilnTexture = {
usage: compiled.spec.usage,
colorSpace:
compiled.spec.usage === 'albedo' || compiled.spec.usage === 'emissive' ? 'srgb' : 'linear',
width: compiled.spec.width,
height: compiled.spec.height,
hasAlpha: compiled.pixels.some((v, i) => i % 4 === 3 && v < 255),
};
return texture;
}
export interface AtlasUVOptionsV1 {
inputOrigin: 'top-left' | 'bottom-left';
mode: 'content-boundary' | 'texel-center';
/**
* Which UV components the region mapping owns. Default `uv` replaces both.
* `u-only` rescales U into a full-height column and passes V through
* untouched, for a runtime that reads V as a per-vertex gradient rather than
* an atlas coordinate — the `uv-y` foliage wind weight is the known case.
*/
axes?: 'uv' | 'u-only';
}
function manifestOf(atlas: THREE.Texture | TextureAtlasManifestV1): TextureAtlasManifestV1 {
const value = (atlas as THREE.Texture)?.isTexture
? (atlas as THREE.Texture).userData.kilnAtlas?.manifest
: atlas;
if (!value || typeof value !== 'object')
atlasFailure('an atlas texture or compiled manifest is required.');
canonicalAtlasMetadataJsonV1(value);
const manifest = value as TextureAtlasManifestV1;
const limits =
manifest.compilerId === TEXTURE_ATLAS_COMPILER_ID_V1_2
? TEXTURE_ATLAS_LIMITS_V1_2
: TEXTURE_ATLAS_LIMITS;
if (
manifest.version !== 'kiln.atlas-manifest.v1' ||
!(TEXTURE_ATLAS_COMPILER_IDS as readonly unknown[]).includes(manifest.compilerId) ||
manifest.origin !== 'top-left' ||
!Array.isArray(manifest.regions) ||
!manifest.regions.length ||
manifest.regions.length > limits.regions ||
!Number.isSafeInteger(manifest.width) ||
manifest.width < 4 ||
manifest.width > limits.edge ||
!Number.isSafeInteger(manifest.height) ||
manifest.height < 4 ||
manifest.height > limits.edge
)
atlasFailure('invalid atlas manifest dimensions/version.');
const { manifestHash, ...payload } = manifest;
if (
`sha256:${sha256Hex(`kiln.atlas-manifest.v1\n${canonicalAtlasMetadataJsonV1(payload)}`)}` !==
manifestHash
)
atlasFailure('atlas manifest identity mismatch.');
return manifest;
}
export function remapUVToAtlas(
geometry: THREE.BufferGeometry,
atlas: THREE.Texture | TextureAtlasManifestV1,
name: string,
options: AtlasUVOptionsV1,
): THREE.BufferGeometry {
const manifest = manifestOf(atlas);
canonicalAtlasMetadataJsonV1(options);
if (
!options ||
typeof options !== 'object' ||
Array.isArray(options) ||
Object.keys(options).some((k) => !['inputOrigin', 'mode', 'axes'].includes(k)) ||
!['top-left', 'bottom-left'].includes(options.inputOrigin) ||
!['content-boundary', 'texel-center'].includes(options.mode)
)
atlasFailure('explicit inputOrigin and content-boundary/texel-center mode are required.');
if (options.axes !== undefined && !['uv', 'u-only'].includes(options.axes))
atlasFailure('axes must be uv (default, both components) or u-only.');
const uOnly = options.axes === 'u-only';
if (uOnly && options.inputOrigin !== 'top-left')
atlasFailure(
'u-only requires inputOrigin top-left: V passes through unmapped, so a bottom-left flip would invert the gradient it carries.',
);
const region = manifest.regions.find((r) => r.name === name);
if (!region) atlasFailure(`unknown named region ${String(name)}.`);
const { x, y, width: w, height: h } = region.content;
if (
![x, y, w, h].every(Number.isSafeInteger) ||
x < 0 ||
y < 0 ||
w < 1 ||
h < 1 ||
x + w > manifest.width ||
y + h > manifest.height
)
atlasFailure('invalid region content rectangle.');
// Passing V through only addresses the region when the region is the whole
// column: a guttered or packed rectangle would sample outside it instead.
if (uOnly && (y !== 0 || h !== manifest.height))
atlasFailure(
`u-only requires a region spanning the full atlas height; ${name} covers rows ${y}..${y + h} of ${manifest.height}. Lay the atlas out as full-height columns with gutter 0.`,
);
const uv = geometry?.getAttribute?.('uv'),
position = geometry?.getAttribute?.('position');
if (
!position ||
!uv ||
uv.itemSize !== 2 ||
uv.count !== position.count ||
uv.count < 1 ||
uv.count > TEXTURE_ATLAS_LIMITS.uvVertices ||
(uv as THREE.InstancedBufferAttribute).isInstancedBufferAttribute ||
(
(uv as THREE.InterleavedBufferAttribute).data as
| (THREE.InterleavedBuffer & { isInstancedInterleavedBuffer?: boolean })
| undefined
)?.isInstancedInterleavedBuffer
)
atlasFailure(
'matching per-vertex UV0 and positions are required; per-instance UVs are unsupported.',
);
let bytes = uv.count * 8;
const interleavedBuffers = new Set<ArrayBufferLike>();
const count = (attribute: THREE.BufferAttribute | THREE.InterleavedBufferAttribute) => {
if ((attribute as THREE.InterleavedBufferAttribute).isInterleavedBufferAttribute) {
// Three's geometry-copy data cache deduplicates interleaved backing buffers.
const buffer = attribute.array.buffer;
if (!interleavedBuffers.has(buffer)) {
interleavedBuffers.add(buffer);
bytes += buffer.byteLength;
}
} else {
// Ordinary attributes/morphs/index clone independently even with shared input arrays.
// Typed convenience subclasses may allocate in both constructor and copy.
bytes +=
attribute.array.byteLength *
(attribute.constructor === THREE.BufferAttribute ||
attribute.constructor === THREE.InstancedBufferAttribute
? 1
: 2);
}
};
for (const attr of Object.values(geometry.attributes)) count(attr);
for (const attrs of Object.values(geometry.morphAttributes))
for (const attr of attrs) count(attr);
if (geometry.index) count(geometry.index);
if (bytes > TEXTURE_ATLAS_LIMITS.uvAttributeBytes)
atlasFailure('owned UV clone attribute allocation budget exceeded.');
for (let i = 0; i < uv.count; i++)
if (![uv.getX(i), uv.getY(i)].every((v) => Number.isFinite(v) && v >= 0 && v <= 1))
atlasFailure('UV0 must be finite in the unit domain [0,1]; region tiling is unsupported.');
const center = options.mode === 'texel-center',
su = (w - (center ? 1 : 0)) / manifest.width,
sv = (h - (center ? 1 : 0)) / manifest.height;
const bottom = options.inputOrigin === 'bottom-left';
const offset: [number, number] = [
(x + (center ? 0.5 : 0)) / manifest.width,
uOnly ? 0 : (y + (bottom ? h - (center ? 0.5 : 0) : center ? 0.5 : 0)) / manifest.height,
];
const scale: [number, number] = [su, uOnly ? 1 : bottom ? -sv : sv];
const output = remapUV(geometry, { scale, offset });
output.userData.kilnAtlasBinding = {
manifestHash: manifest.manifestHash,
specHash: manifest.specHash,
layoutHash: manifest.layoutHash,
region: name,
content: structuredClone(region.content),
allocation: structuredClone(region.allocation),
inputOrigin: options.inputOrigin,
mode: options.mode,
// Omitted for the default, so stamps and exported extras predating u-only
// stay byte-identical.
...(uOnly ? { axes: 'u-only' as const } : {}),
scale,
offset,
};
return output;
}