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
import { createHash } from 'node:crypto';
import { describe, expect, test } from 'bun:test';
import {
createHeightfieldArtifactV1,
decodeHeightfieldArtifactV1,
encodeHeightfieldArtifactV1,
hashHeightfieldArtifactV1,
HEIGHTFIELD_QUANTIZATION_STEP,
heightfieldGround,
heightfieldMeshDataV1,
stampHeightfieldArtifactV1,
} from './terrain';
import { flatGround } from './ground';
describe('HeightfieldArtifactV1', () => {
test('is deterministic by seed and hashes the exact canonical bytes', async () => {
const input = {
seed: 42,
origin: [-4, -4] as [number, number],
cellSize: 2,
width: 5,
height: 5,
baseHeight: 1,
amplitude: 3,
frequency: 0.2,
};
const a = createHeightfieldArtifactV1(input);
const b = createHeightfieldArtifactV1(input);
const c = createHeightfieldArtifactV1({ ...input, seed: 43 });
expect(encodeHeightfieldArtifactV1(a)).toEqual(encodeHeightfieldArtifactV1(b));
expect(a.heights).not.toEqual(c.heights);
expect(
a.heights.every((height) => Number.isInteger(height / HEIGHTFIELD_QUANTIZATION_STEP)),
).toBe(true);
const expected = createHash('sha256').update(encodeHeightfieldArtifactV1(a)).digest('hex');
expect(await hashHeightfieldArtifactV1(a)).toBe(expected);
expect(decodeHeightfieldArtifactV1(encodeHeightfieldArtifactV1(a))).toEqual(a);
});
test('samples bilinear height, clamped edges, and normalized terrain normals', () => {
const artifact = {
schemaVersion: 'kiln.heightfield.v1' as const,
seed: 1,
origin: [10, 20] as [number, number],
cellSize: 2,
width: 2,
height: 2,
baseHeight: 0,
amplitude: 0,
frequency: 1,
stamps: [],
heights: [0, 2, 4, 6],
};
const sampler = heightfieldGround(artifact);
expect(sampler.heightAt(11, 21)).toBe(3);
expect(sampler.heightAt(-100, -100)).toBe(0);
expect(sampler.heightAt(100, 100)).toBe(6);
const normal = sampler.normalAt(11, 21);
expect(Math.hypot(...normal)).toBeCloseTo(1, 12);
expect(normal[1]).toBeGreaterThan(0);
expect(flatGround(9).normalAt(0, 0)).toEqual([0, 1, 0]);
const mesh = heightfieldMeshDataV1(artifact);
expect(mesh.positions).toEqual([10, 0, 20, 12, 2, 20, 10, 4, 22, 12, 6, 22]);
expect(mesh.indices).toEqual([0, 2, 1, 1, 2, 3]);
expect(mesh.normals).toHaveLength(12);
});
test('applies bounded road, path, and pad stamps without mutating the source', () => {
const source = createHeightfieldArtifactV1({
seed: 1,
origin: [0, 0],
cellSize: 1,
width: 7,
height: 7,
baseHeight: 5,
amplitude: 0,
frequency: 1,
});
const stamped = stampHeightfieldArtifactV1(source, [
{
kind: 'road',
points: [
[0, 3],
[6, 3],
],
halfWidth: 0.6,
targetHeight: 1,
},
{
kind: 'path',
points: [
[3, 0],
[3, 6],
],
halfWidth: 0.4,
targetHeight: 2,
},
{ kind: 'pad', center: [5, 5], halfExtents: [0.75, 0.75], targetHeight: 3 },
]);
expect(source.heights.every((height) => height === 5)).toBe(true);
const sampler = heightfieldGround(stamped);
expect(sampler.heightAt(1, 3)).toBe(1);
expect(sampler.heightAt(3, 1)).toBe(2);
expect(sampler.heightAt(5, 5)).toBe(3);
expect(stamped.stamps).toHaveLength(3);
});
test('fails closed on unknown versions, invalid dimensions, and non-positive stamp extents', () => {
expect(() =>
createHeightfieldArtifactV1({
seed: 1,
origin: [0, 0],
cellSize: 1,
width: 258,
height: 2,
baseHeight: 0,
amplitude: 1,
frequency: 1,
}),
).toThrow();
expect(() =>
decodeHeightfieldArtifactV1(
new TextEncoder().encode(JSON.stringify({ schemaVersion: 'kiln.heightfield.v2' })),
),
).toThrow();
const flat = createHeightfieldArtifactV1({
seed: 1,
origin: [0, 0],
cellSize: 1,
width: 2,
height: 2,
baseHeight: 0,
amplitude: 0,
frequency: 1,
});
expect(() =>
stampHeightfieldArtifactV1(flat, [
{ kind: 'pad', center: [0, 0], halfExtents: [0, 1], targetHeight: 0 },
]),
).toThrow();
});
test('decode rejects every noncanonical byte representation and invalid UTF-8', () => {
const artifact = createHeightfieldArtifactV1({
seed: 3,
origin: [0, 0],
cellSize: 1,
width: 2,
height: 2,
baseHeight: 0,
amplitude: 0,
frequency: 1,
});
const canonical = encodeHeightfieldArtifactV1(artifact);
const text = new TextDecoder().decode(canonical);
expect(decodeHeightfieldArtifactV1(canonical)).toEqual(artifact);
expect(() => decodeHeightfieldArtifactV1(new TextEncoder().encode(` ${text}`))).toThrow(
'not canonical',
);
const parsed = JSON.parse(text) as Record<string, unknown>;
const reversed = Object.fromEntries(Object.entries(parsed).reverse());
expect(() =>
decodeHeightfieldArtifactV1(new TextEncoder().encode(JSON.stringify(reversed))),
).toThrow('not canonical');
const nonquantized = structuredClone(parsed) as { heights: number[] };
nonquantized.heights[0] = HEIGHTFIELD_QUANTIZATION_STEP / 3;
expect(() =>
decodeHeightfieldArtifactV1(new TextEncoder().encode(JSON.stringify(nonquantized))),
).toThrow('not canonical');
expect(() => decodeHeightfieldArtifactV1(new Uint8Array([0xc3, 0x28]))).toThrow();
});
});