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
/**
* Strict, browser-safe contracts for model-authored portable materials.
*
* These functions accept `unknown` on purpose. Generated programs are an
* untrusted JSON-shaped boundary even when TypeScript declarations say the
* input is well formed. Canonicalization rejects executable references,
* inherited state, unknown fields, and work outside the fixed budgets before
* the pixel compiler allocates an output buffer.
*/
import {
CELLULAR_FEATURES,
type CellularFeature,
MAX_CELLULAR_METRIC,
MAX_CELLULAR_WEIGHT,
MIN_CELLULAR_METRIC,
} from './procedural-cellular';
import { TEXTURE_USAGES, type TextureUsage } from './texture-contract';
import {
AuthoringDiagnosticError,
type AuthoringDiagnostic,
} from './evaluator/authoring-diagnostic';
export const PROCEDURAL_TEXTURE_SPEC_VERSION = 2 as const;
export const PORTABLE_MATERIAL_SPEC_VERSION = 2 as const;
export const MAX_PROCEDURAL_SIZE = 1024;
export const MIN_PROCEDURAL_SIZE = 4;
export const MAX_PROCEDURAL_LAYERS = 8;
export const MAX_NOISE_OCTAVES = 6;
export const MAX_PROCEDURAL_NAME_LENGTH = 80;
export const MAX_PROCEDURAL_PATTERN_COUNT = 256;
export const MAX_PORTABLE_MATERIAL_TEXTURES = 5;
/** Four 1024-square maps, or a larger number of smaller maps. */
export const MAX_PORTABLE_MATERIAL_TEXELS = 4 * 1024 * 1024;
export type ProceduralBlend = 'normal' | 'multiply' | 'screen' | 'overlay';
interface LayerCommon {
blend?: ProceduralBlend;
opacity?: number;
}
export type ProceduralLayer = LayerCommon &
(
| { op: 'solid'; color: number }
| { op: 'checker'; colorA: number; colorB: number; squares?: number }
| { op: 'stripes'; colorA: number; colorB: number; count?: number; angleDeg?: number }
| { op: 'gradient'; from: number; to: number; angleDeg?: number }
| {
op: 'bricks';
brick: number;
mortar: number;
rows?: number;
cols?: number;
mortarWidth?: number;
stagger?: number;
}
| {
op: 'noise';
colorA: number;
colorB: number;
scale?: number;
octaves?: number;
seed?: number;
}
| {
op: 'cellular';
colorA: number;
colorB: number;
cellsX?: number;
cellsY?: number;
seed?: number;
jitterX?: number;
jitterY?: number;
metricX?: number;
metricY?: number;
weight?: number;
feature?: CellularFeature;
range?: number;
borderOpen?: number;
borderWidth?: number;
facetSlope?: number;
facetBlend?: number;
}
);
/** Historical source shape. Absence of schemaVersion means V1. */
export interface ProceduralTextureSpecV1 {
schemaVersion?: 1;
size?: number;
usage?: TextureUsage;
name?: string;
layers: ProceduralLayer[];
}
/** Current source shape. Validation still happens at runtime. */
export interface ProceduralTextureSpecV2 {
schemaVersion: 2;
size?: number;
usage?: TextureUsage;
name?: string;
layers: ProceduralLayer[];
}
/** Compatibility name retained for existing generated programs. */
export type ProceduralTextureSpec = ProceduralTextureSpecV1 | ProceduralTextureSpecV2;
interface CanonicalLayerCommon {
blend: ProceduralBlend;
opacity: number;
}
export type CanonicalProceduralLayerV2 = CanonicalLayerCommon &
(
| { op: 'solid'; color: number }
| { op: 'checker'; colorA: number; colorB: number; squares: number }
| { op: 'stripes'; colorA: number; colorB: number; count: number; angleDeg: number }
| { op: 'gradient'; from: number; to: number; angleDeg: number }
| {
op: 'bricks';
brick: number;
mortar: number;
rows: number;
cols: number;
mortarWidth: number;
stagger: number;
}
| {
op: 'noise';
colorA: number;
colorB: number;
scale: number;
octaves: number;
seed: number;
}
| {
op: 'cellular';
colorA: number;
colorB: number;
cellsX: number;
cellsY: number;
seed: number;
jitterX: number;
jitterY: number;
metricX: number;
metricY: number;
weight: number;
feature: CellularFeature;
range: number;
borderOpen: number;
borderWidth: number;
facetSlope: number;
facetBlend: number;
}
);
export interface CanonicalProceduralTextureSpecV2 {
schemaVersion: 2;
size: number;
usage: TextureUsage;
name?: string;
layers: CanonicalProceduralLayerV2[];
}
export type PortableTextureRefV2 =
| { kind: 'procedural'; spec: ProceduralTextureSpecV2 }
| { kind: 'resource'; resourceId: string };
export interface PortableMaterialSpecV2 {
schemaVersion: 2;
model: 'pbrMetallicRoughness';
name?: string;
baseColor?: number;
roughness?: number;
metalness?: number;
emissive?: number;
emissiveIntensity?: number;
alphaMode?: 'opaque' | 'mask' | 'blend';
alphaCutoff?: number;
doubleSided?: boolean;
textures?: {
baseColor?: PortableTextureRefV2;
normal?: PortableTextureRefV2;
metallicRoughness?: PortableTextureRefV2;
emissive?: PortableTextureRefV2;
occlusion?: PortableTextureRefV2;
};
}
export type CanonicalPortableTextureRefV2 =
| { kind: 'procedural'; spec: CanonicalProceduralTextureSpecV2 }
| { kind: 'resource'; resourceId: string };
export interface CanonicalPortableMaterialSpecV2 {
schemaVersion: 2;
model: 'pbrMetallicRoughness';
name?: string;
baseColor?: number;
roughness: number;
metalness: number;
emissive?: number;
emissiveIntensity: number;
alphaMode: 'opaque' | 'mask' | 'blend';
alphaCutoff: number;
doubleSided: boolean;
textures: {
baseColor?: CanonicalPortableTextureRefV2;
normal?: CanonicalPortableTextureRefV2;
metallicRoughness?: CanonicalPortableTextureRefV2;
emissive?: CanonicalPortableTextureRefV2;
occlusion?: CanonicalPortableTextureRefV2;
};
}
export class ProceduralTextureError extends AuthoringDiagnosticError {
constructor(message: string, diagnostic?: AuthoringDiagnostic) {
super(diagnostic, message);
this.name = 'ProceduralTextureError';
}
}
const OPS = ['solid', 'checker', 'stripes', 'gradient', 'bricks', 'noise', 'cellular'] as const;
const BLENDS: readonly ProceduralBlend[] = ['normal', 'multiply', 'screen', 'overlay'];
const FORBIDDEN_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
function strictRecord(value: unknown, path: string): Record<string, unknown> {
if (!value || typeof value !== 'object' || Array.isArray(value)) {
throw new ProceduralTextureError(`${path} must be a plain JSON object.`);
}
const prototype = Object.getPrototypeOf(value);
if (prototype !== Object.prototype && prototype !== null) {
throw new ProceduralTextureError(
`${path} must be a plain JSON object with no custom prototype.`,
);
}
for (const key of Reflect.ownKeys(value)) {
if (typeof key !== 'string') {
throw new ProceduralTextureError(`${path} must not contain symbol keys.`);
}
if (FORBIDDEN_KEYS.has(key)) {
throw new ProceduralTextureError(`${path} contains forbidden key ${JSON.stringify(key)}.`);
}
if (!Object.prototype.propertyIsEnumerable.call(value, key)) {
throw new ProceduralTextureError(`${path}.${key} must be an enumerable JSON field.`);
}
const descriptor = Object.getOwnPropertyDescriptor(value, key);
if (!descriptor || !('value' in descriptor)) {
throw new ProceduralTextureError(`${path}.${key} must be a plain JSON data field.`);
}
}
return value as Record<string, unknown>;
}
function strictArray(value: unknown, path: string): unknown[] {
if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) {
throw new ProceduralTextureError(`${path} must be a plain JSON array.`);
}
for (const key of Reflect.ownKeys(value)) {
if (typeof key !== 'string') {
throw new ProceduralTextureError(`${path} must not contain symbol keys.`);
}
if (key === 'length') continue;
if (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length) {
throw new ProceduralTextureError(
`${path} has non-index JSON array key ${JSON.stringify(key)}.`,
);
}
}
for (let index = 0; index < value.length; index++) {
if (!Object.hasOwn(value, index)) {
throw new ProceduralTextureError(
`${path} must be a dense JSON array (missing index ${index}).`,
);
}
}
return value;
}
function assertKeys(
record: Record<string, unknown>,
allowed: readonly string[],
path: string,
): void {
const allow = new Set(allowed);
for (const key of Object.keys(record)) {
if (!allow.has(key)) {
throw new ProceduralTextureError(
`${path} has unknown key ${JSON.stringify(key)}.`,
'PROCEDURAL_TEXTURE_UNKNOWN_KEY',
);
}
}
}
function color(value: unknown, path: string, diagnostic?: AuthoringDiagnostic): number {
if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > 0xffffff) {
throw new ProceduralTextureError(
`${path} must be a color integer between 0x000000 and 0xffffff, got ${JSON.stringify(value)}.`,
diagnostic,
);
}
return value;
}
function integer(value: unknown, path: string, fallback: number, min: number, max: number): number {
if (value === undefined) return fallback;
if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max) {
throw new ProceduralTextureError(
`${path} must be a whole number between ${min} and ${max}, got ${JSON.stringify(value)}.`,
);
}
return value;
}
function finite(
value: unknown,
path: string,
fallback: number,
min: number,
max: number,
diagnostic?: AuthoringDiagnostic,
): number {
if (value === undefined) return fallback;
if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
throw new ProceduralTextureError(
`${path} must be a finite number between ${min} and ${max}, got ${JSON.stringify(value)}.`,
diagnostic,
);
}
return value;
}
function unit(value: unknown, path: string, fallback: number): number {
return finite(value, path, fallback, 0, 1, 'MATERIAL_FRACTION_RANGE');
}
function optionalName(value: unknown, path: string): string | undefined {
if (value === undefined) return undefined;
const hasControlCharacter =
typeof value === 'string' &&
[...value].some((character) => {
const code = character.charCodeAt(0);
return code < 0x20 || code === 0x7f;
});
if (
typeof value !== 'string' ||
value.length === 0 ||
value.length > MAX_PROCEDURAL_NAME_LENGTH ||
hasControlCharacter
) {
throw new ProceduralTextureError(
`${path} must be 1..${MAX_PROCEDURAL_NAME_LENGTH} visible characters.`,
);
}
return value;
}
function usage(value: unknown, path: string, fallback: TextureUsage): TextureUsage {
if (value === undefined) return fallback;
if (!(TEXTURE_USAGES as readonly unknown[]).includes(value)) {
throw new ProceduralTextureError(
`${path} must be one of ${TEXTURE_USAGES.join(', ')}, got ${JSON.stringify(value)}.`,
'PROCEDURAL_TEXTURE_USAGE',
);
}
return value as TextureUsage;
}
function angle(value: unknown, path: string): number {
const bounded = finite(value, path, 0, -36_000, 36_000);
const normalized = ((bounded % 360) + 360) % 360;
return Object.is(normalized, -0) ? 0 : normalized;
}
function blend(record: Record<string, unknown>, path: string): ProceduralBlend {
const value = record['blend'] ?? 'normal';
if (!BLENDS.includes(value as ProceduralBlend)) {
throw new ProceduralTextureError(
`${path}.blend ${JSON.stringify(value)} is not one of ${BLENDS.join(', ')}.`,
'PROCEDURAL_TEXTURE_BLEND',
);
}
return value as ProceduralBlend;
}
/** A control one feature reads. Any other feature has it at its default, so the hash is stable. */
function featureControl(
record: Record<string, unknown>,
path: string,
feature: CellularFeature,
control: { name: string; fallback: number; min: number; max: number },
owners: readonly CellularFeature[],
): number {
const { name, fallback, min, max } = control;
const value = finite(record[name], `${path}.${name}`, fallback, min, max);
if (value !== fallback && !owners.includes(feature)) {
const noun = owners.length > 1 ? 'features' : 'feature';
const named = owners.length > 1 ? owners.join(', ') : JSON.stringify(owners[0]);
throw new ProceduralTextureError(
`${path}.${name} applies only to ${noun} ${named}, not ${JSON.stringify(feature)}. Remove it or change feature.`,
);
}
return value;
}
function cellularFeature(value: unknown, path: string): CellularFeature {
const feature = value ?? 'f1';
if (!(CELLULAR_FEATURES as readonly unknown[]).includes(feature)) {
throw new ProceduralTextureError(
`${path}.feature ${JSON.stringify(feature)} is not one of ${CELLULAR_FEATURES.join(', ')}.`,
);
}
return feature as CellularFeature;
}
function canonicalLayer(value: unknown, index: number): CanonicalProceduralLayerV2 {
const path = `proceduralTexture.layers[${index}]`;
const record = strictRecord(value, path);
const op = record['op'];
if (!(OPS as readonly unknown[]).includes(op)) {
throw new ProceduralTextureError(
`${path}.op ${JSON.stringify(op)} is not one of ${OPS.join(', ')}.`,
);
}
const validatedBlend = blend(record, path);
const validatedOpacity = unit(record['opacity'], `${path}.opacity`, 1);
// The base layer has nothing beneath it. Normalize its ignored compositing
// controls so semantically identical recipes cannot receive different hashes.
const common = {
blend: index === 0 ? ('normal' as const) : validatedBlend,
opacity: index === 0 ? 1 : validatedOpacity,
};
switch (op) {
case 'solid':
assertKeys(record, ['op', 'color', 'blend', 'opacity'], path);
return { op, color: color(record['color'], `${path}.color`), ...common };
case 'checker':
assertKeys(record, ['op', 'colorA', 'colorB', 'squares', 'blend', 'opacity'], path);
return {
op,
colorA: color(record['colorA'], `${path}.colorA`),
colorB: color(record['colorB'], `${path}.colorB`),
squares: integer(record['squares'], `${path}.squares`, 8, 1, MAX_PROCEDURAL_PATTERN_COUNT),
...common,
};
case 'stripes':
assertKeys(record, ['op', 'colorA', 'colorB', 'count', 'angleDeg', 'blend', 'opacity'], path);
return {
op,
colorA: color(record['colorA'], `${path}.colorA`),
colorB: color(record['colorB'], `${path}.colorB`),
count: integer(record['count'], `${path}.count`, 8, 1, MAX_PROCEDURAL_PATTERN_COUNT),
angleDeg: angle(record['angleDeg'], `${path}.angleDeg`),
...common,
};
case 'gradient':
assertKeys(record, ['op', 'from', 'to', 'angleDeg', 'blend', 'opacity'], path);
return {
op,
from: color(record['from'], `${path}.from`),
to: color(record['to'], `${path}.to`),
angleDeg: angle(record['angleDeg'], `${path}.angleDeg`),
...common,
};
case 'bricks':
assertKeys(
record,
['op', 'brick', 'mortar', 'rows', 'cols', 'mortarWidth', 'stagger', 'blend', 'opacity'],
path,
);
return {
op,
brick: color(record['brick'], `${path}.brick`),
mortar: color(record['mortar'], `${path}.mortar`),
rows: integer(record['rows'], `${path}.rows`, 8, 1, MAX_PROCEDURAL_PATTERN_COUNT),
cols: integer(record['cols'], `${path}.cols`, 4, 1, MAX_PROCEDURAL_PATTERN_COUNT),
mortarWidth: unit(record['mortarWidth'], `${path}.mortarWidth`, 0.06),
stagger: unit(record['stagger'], `${path}.stagger`, 0.5),
...common,
};
case 'noise':
assertKeys(
record,
['op', 'colorA', 'colorB', 'scale', 'octaves', 'seed', 'blend', 'opacity'],
path,
);
return {
op,
colorA: color(record['colorA'], `${path}.colorA`),
colorB: color(record['colorB'], `${path}.colorB`),
scale: integer(record['scale'], `${path}.scale`, 8, 1, MAX_PROCEDURAL_PATTERN_COUNT),
octaves: integer(record['octaves'], `${path}.octaves`, 3, 1, MAX_NOISE_OCTAVES),
seed: integer(record['seed'], `${path}.seed`, 0, -0x80000000, 0x7fffffff),
...common,
};
case 'cellular': {
assertKeys(
record,
[
'op',
'colorA',
'colorB',
'cellsX',
'cellsY',
'seed',
'jitterX',
'jitterY',
'metricX',
'metricY',
'weight',
'feature',
'range',
'borderOpen',
'borderWidth',
'facetSlope',
'facetBlend',
'blend',
'opacity',
],
path,
);
const feature = cellularFeature(record['feature'], path);
return {
op,
colorA: color(record['colorA'], `${path}.colorA`),
colorB: color(record['colorB'], `${path}.colorB`),
cellsX: integer(record['cellsX'], `${path}.cellsX`, 8, 1, MAX_PROCEDURAL_PATTERN_COUNT),
cellsY: integer(record['cellsY'], `${path}.cellsY`, 8, 1, MAX_PROCEDURAL_PATTERN_COUNT),
seed: integer(record['seed'], `${path}.seed`, 0, -0x80000000, 0x7fffffff),
jitterX: unit(record['jitterX'], `${path}.jitterX`, 1),
jitterY: unit(record['jitterY'], `${path}.jitterY`, 1),
metricX: finite(
record['metricX'],
`${path}.metricX`,
1,
MIN_CELLULAR_METRIC,
MAX_CELLULAR_METRIC,
),
metricY: finite(
record['metricY'],
`${path}.metricY`,
1,
MIN_CELLULAR_METRIC,
MAX_CELLULAR_METRIC,
),
weight: finite(record['weight'], `${path}.weight`, 0, 0, MAX_CELLULAR_WEIGHT),
feature,
range: featureControl(
record,
path,
feature,
{ name: 'range', fallback: 1, min: 0.01, max: 8 },
['f1', 'f2', 'f2-f1', 'cell'],
),
borderOpen: featureControl(
record,
path,
feature,
{ name: 'borderOpen', fallback: 0.5, min: 0, max: 1 },
['border'],
),
borderWidth: featureControl(
record,
path,
feature,
{ name: 'borderWidth', fallback: 0.05, min: 0.001, max: 1 },
['border'],
),
facetSlope: featureControl(
record,
path,
feature,
{ name: 'facetSlope', fallback: 0.5, min: 0, max: 1 },
['facet'],
),
facetBlend: featureControl(
record,
path,
feature,
{ name: 'facetBlend', fallback: 0.1, min: 0.001, max: 1 },
['facet'],
),
...common,
};
}
default:
throw new ProceduralTextureError(`${path}.op is unsupported.`);
}
}
export function migrateProceduralTextureSpecV1(input: unknown): ProceduralTextureSpecV2 {
const record = strictRecord(input, 'proceduralTexture');
assertKeys(record, ['schemaVersion', 'size', 'usage', 'name', 'layers'], 'proceduralTexture');
if (record['schemaVersion'] !== undefined && record['schemaVersion'] !== 1) {
throw new ProceduralTextureError(
`proceduralTexture.schemaVersion must be 1 or absent for V1 migration, got ${JSON.stringify(record['schemaVersion'])}.`,
);
}
return {
schemaVersion: 2,
...(record['size'] !== undefined ? { size: record['size'] as number } : {}),
...(record['usage'] !== undefined ? { usage: record['usage'] as TextureUsage } : {}),
...(record['name'] !== undefined ? { name: record['name'] as string } : {}),
layers: record['layers'] as ProceduralLayer[],
};
}
export function canonicalizeProceduralTextureSpecV2(
input: unknown,
): CanonicalProceduralTextureSpecV2 {
const initial = strictRecord(input, 'proceduralTexture');
const source =
initial['schemaVersion'] === undefined || initial['schemaVersion'] === 1
? strictRecord(migrateProceduralTextureSpecV1(initial), 'proceduralTexture')
: initial;
assertKeys(source, ['schemaVersion', 'size', 'usage', 'name', 'layers'], 'proceduralTexture');
if (source['schemaVersion'] !== 2) {
throw new ProceduralTextureError(
`proceduralTexture.schemaVersion must be 2, got ${JSON.stringify(source['schemaVersion'])}.`,
);
}
const size = source['size'] ?? 256;
if (
typeof size !== 'number' ||
!Number.isInteger(size) ||
size < MIN_PROCEDURAL_SIZE ||
size > MAX_PROCEDURAL_SIZE ||
(size & (size - 1)) !== 0
) {
throw new ProceduralTextureError(
`proceduralTexture.size must be a power of two between ${MIN_PROCEDURAL_SIZE} and ${MAX_PROCEDURAL_SIZE}, got ${JSON.stringify(source['size'])}.`,
);
}
const rawLayers = source['layers'];
if (!Array.isArray(rawLayers) || rawLayers.length === 0) {
throw new ProceduralTextureError(
'proceduralTexture.layers must be a non-empty array — the bottom layer is the base pattern.',
);
}
const layers = strictArray(rawLayers, 'proceduralTexture.layers');
if (layers.length > MAX_PROCEDURAL_LAYERS) {
throw new ProceduralTextureError(
`proceduralTexture: ${layers.length} layers exceeds the maximum of ${MAX_PROCEDURAL_LAYERS}.`,
);
}
const name = optionalName(source['name'], 'proceduralTexture.name');
return {
schemaVersion: 2,
size,
usage: usage(source['usage'], 'proceduralTexture.usage', 'albedo'),
...(name !== undefined ? { name } : {}),
layers: layers.map(canonicalLayer),
};
}
function canonicalJson(value: unknown): string {
if (value === null || typeof value !== 'object') return JSON.stringify(value);
if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
const record = value as Record<string, unknown>;
return `{${Object.keys(record)
.sort()
.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
.join(',')}}`;
}
export function canonicalProceduralTextureJsonV2(input: unknown): string {
return canonicalJson(canonicalizeProceduralTextureSpecV2(input));
}
// Browser-safe synchronous SHA-256. Keeping this local avoids a module-load
// `node:crypto` edge in the primitives graph while still giving synchronous
// generated code a stable recipe identity.
const SHA256_K = new Uint32Array([
0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
]);
const rotateRight = (value: number, bits: number): number =>
(value >>> bits) | (value << (32 - bits));
/** Browser-safe SHA-256 shared by versioned recipe contracts. */
export function sha256Hex(text: string): string {
const source = new TextEncoder().encode(text);
const bitLength = source.length * 8;
const paddedLength = Math.ceil((source.length + 9) / 64) * 64;
const bytes = new Uint8Array(paddedLength);
bytes.set(source);
bytes[source.length] = 0x80;
const view = new DataView(bytes.buffer);
view.setUint32(paddedLength - 8, Math.floor(bitLength / 0x100000000), false);
view.setUint32(paddedLength - 4, bitLength >>> 0, false);
const h = new Uint32Array([
0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
]);
const w = new Uint32Array(64);
for (let offset = 0; offset < bytes.length; offset += 64) {
for (let i = 0; i < 16; i++) w[i] = view.getUint32(offset + i * 4, false);
for (let i = 16; i < 64; i++) {
const a = w[i - 15]!;
const b = w[i - 2]!;
const s0 = rotateRight(a, 7) ^ rotateRight(a, 18) ^ (a >>> 3);
const s1 = rotateRight(b, 17) ^ rotateRight(b, 19) ^ (b >>> 10);
w[i] = (w[i - 16]! + s0 + w[i - 7]! + s1) >>> 0;
}
let [a, b, c, d, e, f, g, hh] = h;
for (let i = 0; i < 64; i++) {
const s1 = rotateRight(e!, 6) ^ rotateRight(e!, 11) ^ rotateRight(e!, 25);
const choice = (e! & f!) ^ (~e! & g!);
const temp1 = (hh! + s1 + choice + SHA256_K[i]! + w[i]!) >>> 0;
const s0 = rotateRight(a!, 2) ^ rotateRight(a!, 13) ^ rotateRight(a!, 22);
const majority = (a! & b!) ^ (a! & c!) ^ (b! & c!);
const temp2 = (s0 + majority) >>> 0;
hh = g;
g = f;
f = e;
e = (d! + temp1) >>> 0;
d = c;
c = b;
b = a;
a = (temp1 + temp2) >>> 0;
}
const next = [a!, b!, c!, d!, e!, f!, g!, hh!];
for (let i = 0; i < 8; i++) h[i] = (h[i]! + next[i]!) >>> 0;
}
return [...h].map((value) => value.toString(16).padStart(8, '0')).join('');
}
export function hashProceduralTextureSpecV2(input: unknown): `sha256:${string}` {
return `sha256:${sha256Hex(canonicalProceduralTextureJsonV2(input))}`;
}
const MATERIAL_TEXTURE_USAGE = {
baseColor: 'albedo',
normal: 'normal',
metallicRoughness: 'metallicRoughness',
emissive: 'emissive',
occlusion: 'occlusion',
} as const satisfies Record<string, TextureUsage>;
function canonicalTextureRef(
value: unknown,
slot: keyof typeof MATERIAL_TEXTURE_USAGE,
): CanonicalPortableTextureRefV2 {
const path = `portableMaterial.textures.${slot}`;
if (value === null || typeof value !== 'object' || Array.isArray(value))
throw new ProceduralTextureError(
`${path} must be a typed resource or procedural reference.`,
'PORTABLE_TEXTURE_REFERENCE',
);
const record = strictRecord(value, path);
if (record['kind'] === 'procedural') {
assertKeys(record, ['kind', 'spec'], path);
const spec = canonicalizeProceduralTextureSpecV2(record['spec']);
const expected = MATERIAL_TEXTURE_USAGE[slot];
if (spec.usage !== expected) {
throw new ProceduralTextureError(
`${path} requires procedural usage ${JSON.stringify(expected)}, got ${JSON.stringify(spec.usage)}.`,
'PROCEDURAL_TEXTURE_USAGE',
);
}
return { kind: 'procedural', spec };
}
if (record['kind'] === 'resource') {
assertKeys(record, ['kind', 'resourceId'], path);
const resourceId = record['resourceId'];
if (
typeof resourceId !== 'string' ||
resourceId.length > 128 ||
!/^kiln\.[a-z0-9][a-z0-9._-]+$/.test(resourceId)
) {
throw new ProceduralTextureError(`${path}.resourceId must be a bounded kiln.* resource ID.`);
}
return { kind: 'resource', resourceId };
}
throw new ProceduralTextureError(
`${path}.kind must be "procedural" or "resource".`,
'PORTABLE_TEXTURE_REFERENCE',
);
}
export function canonicalizePortableMaterialSpecV2(
input: unknown,
): CanonicalPortableMaterialSpecV2 {
const record = strictRecord(input, 'portableMaterial');
assertKeys(
record,
[
'schemaVersion',
'model',
'name',
'baseColor',
'roughness',
'metalness',
'emissive',
'emissiveIntensity',
'alphaMode',
'alphaCutoff',
'doubleSided',
'textures',
],
'portableMaterial',
);
if (record['schemaVersion'] !== 2) {
throw new ProceduralTextureError('portableMaterial.schemaVersion must be 2.');
}
if (record['model'] !== 'pbrMetallicRoughness') {
throw new ProceduralTextureError(
'portableMaterial.model must be "pbrMetallicRoughness"; executable shader models are not portable.',
);
}
const textureInput = record['textures'] ?? {};
const textureRecord = strictRecord(textureInput, 'portableMaterial.textures');
const slots = Object.keys(MATERIAL_TEXTURE_USAGE) as Array<keyof typeof MATERIAL_TEXTURE_USAGE>;
assertKeys(textureRecord, slots, 'portableMaterial.textures');
if (Object.keys(textureRecord).length > MAX_PORTABLE_MATERIAL_TEXTURES) {
throw new ProceduralTextureError(
`portableMaterial has more than ${MAX_PORTABLE_MATERIAL_TEXTURES} texture slots.`,
);
}
const textures: CanonicalPortableMaterialSpecV2['textures'] = {};
let proceduralTexels = 0;
for (const slot of slots) {
if (textureRecord[slot] === undefined) continue;
const ref = canonicalTextureRef(textureRecord[slot], slot);
textures[slot] = ref;
if (ref.kind === 'procedural') proceduralTexels += ref.spec.size * ref.spec.size;
}
if (proceduralTexels > MAX_PORTABLE_MATERIAL_TEXELS) {
throw new ProceduralTextureError(
`portableMaterial procedural texture budget is ${proceduralTexels} texels, above ${MAX_PORTABLE_MATERIAL_TEXELS}.`,
);
}
const alphaMode = record['alphaMode'] ?? 'opaque';
if (alphaMode !== 'opaque' && alphaMode !== 'mask' && alphaMode !== 'blend') {
throw new ProceduralTextureError(
'portableMaterial.alphaMode must be opaque, mask, or blend.',
'MATERIAL_ALPHA_MODE',
);
}
if (record['doubleSided'] !== undefined && typeof record['doubleSided'] !== 'boolean') {
throw new ProceduralTextureError('portableMaterial.doubleSided must be boolean.');
}
const name = optionalName(record['name'], 'portableMaterial.name');
return {
schemaVersion: 2,
model: 'pbrMetallicRoughness',
...(name !== undefined ? { name } : {}),
...(record['baseColor'] !== undefined
? {
baseColor: color(
record['baseColor'],
'portableMaterial.baseColor',
'PORTABLE_COLOR_ARGUMENT',
),
}
: {}),
roughness: unit(record['roughness'], 'portableMaterial.roughness', 1),
metalness: unit(record['metalness'], 'portableMaterial.metalness', 0),
...(record['emissive'] !== undefined
? {
emissive: color(
record['emissive'],
'portableMaterial.emissive',
'PORTABLE_COLOR_ARGUMENT',
),
}
: {}),
emissiveIntensity: finite(
record['emissiveIntensity'],
'portableMaterial.emissiveIntensity',
1,
0,
64,
),
alphaMode,
alphaCutoff: unit(record['alphaCutoff'], 'portableMaterial.alphaCutoff', 0.5),
doubleSided: record['doubleSided'] === true,
textures,
};
}