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
/** Advertisable field shapes only. Existing canonicalizers own semantics and budgets. */
import { z } from 'zod';
import {
type CanonicalProceduralTextureSpecV2,
MIN_PROCEDURAL_SIZE,
MAX_PROCEDURAL_SIZE,
MAX_PROCEDURAL_LAYERS,
MAX_PROCEDURAL_PATTERN_COUNT,
MAX_NOISE_OCTAVES,
} from './procedural-material-v2';
import {
MAX_PROCEDURAL_V3_EDGE,
MAX_PROCEDURAL_V3_OPERATIONS,
MAX_PROCEDURAL_V3_VERTICES,
MAX_PROCEDURAL_V3_STAMPS,
MAX_PROCEDURAL_V3_PALETTE,
PROCEDURAL_TEXTURE_V3_COMPILER_ID,
} from './procedural-texture-v3-contract';
import {
TEXTURE_ATLAS_COMPILER_IDS,
TEXTURE_ATLAS_LIMITS,
TEXTURE_ATLAS_LIMITS_V1_2,
TEXTURE_ATLAS_PACK_EDGES,
} from './texture-atlas-contract';
import {
CELLULAR_FEATURES,
MAX_CELLULAR_METRIC,
MAX_CELLULAR_WEIGHT,
MIN_CELLULAR_METRIC,
} from './procedural-cellular';
import {
PORTABLE_MIN_FILTERS_V1,
PORTABLE_MAG_FILTERS_V1,
PORTABLE_WRAPS_V1,
} from './portable-sampler';
import { TEXTURE_USAGES } from './texture-contract';
/** Persisted V2 shape: all canonical fields required, no author defaults or transforms. */
export const canonicalLegacyV2FieldSchema = (() => {
const color = z.number().int().min(0).max(0xffffff);
const count = z.number().int().min(1).max(MAX_PROCEDURAL_PATTERN_COUNT);
const angleDeg = z.number().min(-36000).max(36000);
const unit = z.number().min(0).max(1);
const common = { blend: z.enum(['normal', 'multiply', 'screen', 'overlay']), opacity: unit };
return z
.object({
schemaVersion: z.literal(2),
size: z.number().int().min(MIN_PROCEDURAL_SIZE).max(MAX_PROCEDURAL_SIZE),
usage: z.enum(TEXTURE_USAGES),
name: z.string().min(1).max(80).optional(),
layers: z
.array(
z.discriminatedUnion('op', [
z.object({ op: z.literal('solid'), color, ...common }).strict(),
z
.object({
op: z.literal('checker'),
colorA: color,
colorB: color,
squares: count,
...common,
})
.strict(),
z
.object({
op: z.literal('stripes'),
colorA: color,
colorB: color,
count,
angleDeg,
...common,
})
.strict(),
z
.object({ op: z.literal('gradient'), from: color, to: color, angleDeg, ...common })
.strict(),
z
.object({
op: z.literal('bricks'),
brick: color,
mortar: color,
rows: count,
cols: count,
mortarWidth: unit,
stagger: unit,
...common,
})
.strict(),
z
.object({
op: z.literal('noise'),
colorA: color,
colorB: color,
scale: count,
octaves: z.number().int().min(1).max(MAX_NOISE_OCTAVES),
seed: z.number().int().min(-2147483648).max(2147483647),
...common,
})
.strict(),
z
.object({
op: z.literal('cellular'),
colorA: color,
colorB: color,
cellsX: count,
cellsY: count,
seed: z.number().int().min(-2147483648).max(2147483647),
jitterX: unit,
jitterY: unit,
metricX: z.number().min(MIN_CELLULAR_METRIC).max(MAX_CELLULAR_METRIC),
metricY: z.number().min(MIN_CELLULAR_METRIC).max(MAX_CELLULAR_METRIC),
weight: z.number().min(0).max(MAX_CELLULAR_WEIGHT),
feature: z.enum(CELLULAR_FEATURES),
range: z.number().min(0.01).max(8),
borderOpen: unit,
borderWidth: z.number().min(0.001).max(1),
facetSlope: unit,
facetBlend: z.number().min(0.001).max(1),
...common,
})
.strict(),
]),
)
.min(1)
.max(MAX_PROCEDURAL_LAYERS),
})
.strict();
})();
/** Inject author V2 without a circular import. Optional persisted leaf must have no defaults. */
export function makeMaterialAuthoringSchemas<S extends z.ZodType<CanonicalProceduralTextureSpecV2>>(
legacyV2Schema: S,
canonicalLegacyV2Schema: z.ZodType<CanonicalProceduralTextureSpecV2> = canonicalLegacyV2FieldSchema,
) {
const integer = (min: number, max: number) => z.number().int().min(min).max(max);
const byte = integer(0, 255);
const coordinate = integer(-4096, 4096);
const point = z.tuple([coordinate, coordinate]);
const rgba = z.tuple([byte, byte, byte, byte]);
const usage = z.enum(TEXTURE_USAGES);
const hash = z.templateLiteral(['sha256:', z.string().regex(/^[a-f0-9]{64}$/)]);
const name = z.string().min(1).max(80);
const stableId = z.string().regex(/^[a-z][a-z0-9_-]{0,79}$/);
const mapId = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_.:/-]{0,199}$/);
const dimensions = { width: integer(1, 4096), height: integer(1, 4096) };
const pixelRectangleSchema = z
.object({ x: coordinate, y: coordinate, width: integer(1, 2048), height: integer(1, 2048) })
.strict();
const atlasRectangleSchema = z
.object({ x: integer(0, 4096), y: integer(0, 4096), ...dimensions })
.strict();
const shape = z.discriminatedUnion('kind', [
pixelRectangleSchema.extend({ kind: z.literal('rectangle') }).strict(),
pixelRectangleSchema.extend({ kind: z.literal('ellipse') }).strict(),
z
.object({
kind: z.literal('polygon'),
points: z.array(point).min(3).max(MAX_PROCEDURAL_V3_VERTICES),
})
.strict(),
z.object({ kind: z.literal('line'), from: point, to: point, width: integer(1, 2048) }).strict(),
]);
const paint = z.object({ op: z.literal('paint'), shape, rgba, opacity: byte }).strict();
const mask = z
.object({ op: z.literal('mask'), shape, alpha: byte, invert: z.boolean() })
.strict();
const stamps = z
.object({
op: z.literal('stamps'),
shape,
rgba,
opacity: byte,
count: integer(1, MAX_PROCEDURAL_V3_STAMPS),
seed: integer(0, 0xffffffff),
area: pixelRectangleSchema,
periodic: z.boolean(),
})
.strict();
const legacy = z
.object({ op: z.literal('legacy-v2'), spec: legacyV2Schema, alpha: byte, opacity: byte })
.strict();
const palette = z
.object({
colors: z.array(integer(0, 0xffffff)).min(1).max(MAX_PROCEDURAL_V3_PALETTE),
dither: z.enum(['none', 'bayer4']),
})
.strict();
const proceduralBase = {
schemaVersion: z.literal(3),
width: integer(4, MAX_PROCEDURAL_V3_EDGE),
height: integer(4, MAX_PROCEDURAL_V3_EDGE),
usage,
name: name.optional(),
background: rgba,
};
const canonicalProceduralTextureSpecV3Schema = z
.object({
...proceduralBase,
operations: z
.array(
z.discriminatedUnion('op', [
paint,
mask,
stamps,
legacy.extend({ spec: canonicalLegacyV2Schema }),
]),
)
.max(MAX_PROCEDURAL_V3_OPERATIONS),
palette: palette.optional(),
})
.strict();
const proceduralTextureSpecV3Schema = z
.object({
...proceduralBase,
usage: usage.optional(),
background: rgba.optional(),
operations: z
.array(
z.discriminatedUnion('op', [
paint.partial({ opacity: true }),
mask.partial({ alpha: true, invert: true }),
stamps.partial({ opacity: true, periodic: true }),
legacy.partial({ alpha: true, opacity: true }),
]),
)
.max(MAX_PROCEDURAL_V3_OPERATIONS),
palette: palette.partial({ dither: true }).optional(),
})
.strict();
const portableSamplerSchema = z
.object({
minFilter: z.enum(PORTABLE_MIN_FILTERS_V1),
magFilter: z.enum(PORTABLE_MAG_FILTERS_V1),
wrapS: z.enum(PORTABLE_WRAPS_V1),
wrapT: z.enum(PORTABLE_WRAPS_V1),
})
.strict();
const materialMapPinSchema = z
.object({ resourceId: stableId, revisionId: hash, sha256: hash })
.strict();
const resourceSource = z
.object({
kind: z.literal('resource'),
resourceId: mapId,
pin: materialMapPinSchema,
expected: z
.object({ ...dimensions, imageSha256: hash, decodedPixelHash: hash })
.partial()
.strict()
.optional(),
})
.strict();
const region = z
.object({
name: stableId,
content: atlasRectangleSchema,
gutter: integer(0, 32),
edgeMode: z.enum(['copy-edge', 'mask-rgb-dilate']),
source: z.discriminatedUnion('kind', [
z
.object({ kind: z.literal('procedural'), spec: canonicalProceduralTextureSpecV3Schema })
.strict(),
resourceSource,
]),
crop: atlasRectangleSchema.optional(),
packed: z.literal(true).optional(),
})
.strict();
// Packed atlases (compiler v1.2) raise the edge and counts; the canonicalizer applies the
// exact per-version limit.
const atlasBase = {
schemaVersion: z.literal(1),
width: integer(4, TEXTURE_ATLAS_LIMITS_V1_2.edge),
height: integer(4, TEXTURE_ATLAS_LIMITS_V1_2.edge),
usage,
sampler: portableSamplerSchema,
};
const packEdge = z.union(
TEXTURE_ATLAS_PACK_EDGES.map((edge) => z.literal(edge)) as [
z.ZodLiteral<1024>,
z.ZodLiteral<2048>,
],
);
const canonicalTextureAtlasSpecV1Schema = z
.object({
...atlasBase,
regions: z.array(region).min(1).max(TEXTURE_ATLAS_LIMITS_V1_2.regions),
pack: z
.object({ edge: packEdge, gutter: integer(0, 32), algorithm: z.literal('maxrects') })
.strict()
.optional(),
})
.strict();
const textureAtlasSpecV1Schema = z
.object({
...atlasBase,
width: atlasBase.width.optional(),
height: atlasBase.height.optional(),
pack: z
.object({
edge: packEdge,
gutter: integer(0, 32).optional(),
algorithm: z.literal('maxrects').optional(),
})
.strict()
.optional(),
sampler: portableSamplerSchema.optional(),
regions: z
.array(
region
.extend({
source: z.discriminatedUnion('kind', [
z
.object({ kind: z.literal('procedural'), spec: proceduralTextureSpecV3Schema })
.strict(),
resourceSource,
]),
})
.partial({ content: true, gutter: true, edgeMode: true }),
)
.min(1)
.max(TEXTURE_ATLAS_LIMITS_V1_2.regions),
})
.strict();
const verifiedPinnedMaterialMapDescriptorSchema = z
.object({
materialId: stableId,
revisionId: hash,
resourceId: mapId,
slot: z.enum(['baseColor', 'normal', 'metallicRoughness', 'emissive', 'occlusion']),
usage,
colorSpace: z.enum(['srgb', 'linear']),
...dimensions,
encodedByteLength: integer(1, TEXTURE_ATLAS_LIMITS.encodedSourceBytes),
imageSha256: hash,
decodedPixelHash: hash.optional(),
})
.strict();
const sourceManifestBase = {
id: z.string().min(1).max(1024),
...dimensions,
decodedPixelHash: hash,
};
const sourceManifest = z.discriminatedUnion('kind', [
z
.object({
...sourceManifestBase,
kind: z.literal('procedural'),
recipeHash: hash,
compilerId: z.literal(PROCEDURAL_TEXTURE_V3_COMPILER_ID),
})
.strict(),
z
.object({
...sourceManifestBase,
kind: z.literal('resource'),
descriptor: verifiedPinnedMaterialMapDescriptorSchema,
})
.strict(),
]);
const textureAtlasManifestV1Schema = z
.object({
version: z.literal('kiln.atlas-manifest.v1'),
compilerId: z.enum(TEXTURE_ATLAS_COMPILER_IDS),
width: atlasBase.width,
height: atlasBase.height,
usage,
origin: z.literal('top-left'),
sampler: portableSamplerSchema,
specHash: hash,
layoutHash: hash,
decodedPixelHash: hash,
atlasPixelHash: hash,
sources: z.array(sourceManifest).min(1).max(TEXTURE_ATLAS_LIMITS_V1_2.sources),
regions: z
.array(
z
.object({
name: stableId,
content: atlasRectangleSchema,
allocation: atlasRectangleSchema,
crop: atlasRectangleSchema,
sourceId: z.string().min(1).max(1024),
})
.strict(),
)
.min(1)
.max(TEXTURE_ATLAS_LIMITS_V1_2.regions),
manifestHash: hash,
})
.strict();
return {
portableSamplerSchema,
proceduralTextureSpecV3Schema,
canonicalProceduralTextureSpecV3Schema,
textureAtlasSpecV1Schema,
canonicalTextureAtlasSpecV1Schema,
textureAtlasManifestV1Schema,
materialMapPinSchema,
verifiedPinnedMaterialMapDescriptorSchema,
};
}