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 { facingToRotY } from './layout';
import type { SceneModelJSON } from './model';
import { PlacementModel } from './model';
import {
WORLD_DOCUMENT_V2_SCHEMA_VERSION,
canonicalWorldDocumentV2Json,
hashWorldDocumentV2,
migrateSceneModelV1ToWorldDocumentV2,
parseWorldDocumentV2,
reconcileWorldDocumentV2Objects,
safeParseWorldDocumentV2,
worldDocumentV2ToSceneModelJSON,
} from './world-document';
const HOUSE_SHA = '1'.repeat(64);
const TREE_SHA = '2'.repeat(64);
function v1Model(): SceneModelJSON {
return {
name: 'Exact legacy scene',
seed: 17,
catalog: [
{
generationId: 'house',
name: 'House',
bbox: { min: [-2, -0.25, -3], max: [4, 6, 3] },
role: 'building',
tier: 'B',
},
{
generationId: 'tree',
name: 'Tree',
bbox: { min: [-1, 0, -1], max: [1, 8, 1] },
tags: ['vegetation'],
role: 'fill',
},
],
statements: [
{
kind: 'place',
stmtId: 's4',
alias: 'house_exact',
generationId: 'house',
role: 'hero',
scale: 1.125,
at: [12.3456789, -9.25],
face: -37.75,
exact: { pos: [12.3456789, 0.03125, -9.25], rotYDeg: -37.75 },
provenance: { sourcePrompt: 'Put the house on the ridge.' },
},
{
kind: 'ring',
stmtId: 's9',
alias: 'trees',
generationId: 'tree',
role: 'fill',
scale: 0.85,
center: [0, 0],
count: 3,
radius: 20,
faceOut: true,
group: 'grove',
},
],
environment: 'edo',
backdrop: { kind: 'fuji', pos: [0, 0, -80], scale: 1.5 },
paint: [
{
kind: 'stone-path',
shape: { type: 'strip', axis: 'z', offset: 2, half: 1.5, from: -20, to: 20 },
},
],
};
}
const migrationOptions = {
worldId: 'scene-123',
artifactSha256ByGenerationId: { house: HOUSE_SHA, tree: TREE_SHA },
lightingPresetId: 'legacy-scene-v1',
} as const;
describe('WorldDocumentV2 contract', () => {
test('migrates v1 deterministically and preserves every evaluated transform exactly', () => {
const source = v1Model();
const expected = PlacementModel.fromJSON(source).placements().placements;
const a = migrateSceneModelV1ToWorldDocumentV2(source, migrationOptions);
const b = migrateSceneModelV1ToWorldDocumentV2(source, migrationOptions);
expect(a).toEqual(b);
expect(a.schemaVersion).toBe(WORLD_DOCUMENT_V2_SCHEMA_VERSION);
expect(a.assets.map((asset) => [asset.generationId, asset.artifactSha256])).toEqual([
['house', HOUSE_SHA],
['tree', TREE_SHA],
]);
expect(
a.objects.map((object) => ({
instanceId: object.id,
generationId: a.assets.find((asset) => asset.refId === object.assetRefId)!.generationId,
pos: object.transform.position,
rotYDeg: object.transform.rotationYDeg,
scale: object.transform.uniformScale,
stmtId: object.provenance.sourceStatementId,
})),
).toEqual(expected);
expect(a.environment).toEqual({
presetId: 'edo',
lightingPresetId: 'legacy-scene-v1',
backdrop: source.backdrop,
groundPaint: source.paint!,
});
expect(a.terrain).toEqual({ kind: 'flat', height: 0 });
expect(a.authored).toEqual({ zones: [], paths: [], sockets: [] });
expect(a.collisionArtifacts).toEqual([]);
expect(a.spawns).toEqual([]);
});
test('projects canonical objects to exact v1 places for drift-free refine', () => {
const world = migrateSceneModelV1ToWorldDocumentV2(v1Model(), migrationOptions);
const projected = worldDocumentV2ToSceneModelJSON(world);
const placements = PlacementModel.fromJSON(projected).placements().placements;
expect(
placements.map(({ instanceId, generationId, pos, rotYDeg, scale }) => ({
instanceId,
generationId,
pos,
rotYDeg,
scale,
})),
).toEqual(
world.objects.map((object) => ({
instanceId: object.id,
generationId: world.assets.find((asset) => asset.refId === object.assetRefId)!.generationId,
pos: object.transform.position,
rotYDeg: object.transform.rotationYDeg,
scale: object.transform.uniformScale,
})),
);
expect(
projected.statements.every((statement) => statement.kind === 'place' && statement.exact),
).toBe(true);
expect(projected.environment).toBe('edo');
expect(projected.backdrop).toEqual(v1Model().backdrop);
expect(projected.paint).toEqual(v1Model().paint);
});
test('projected exact places remain editable through move, face, and group operations', () => {
const world = migrateSceneModelV1ToWorldDocumentV2(v1Model(), migrationOptions);
const model = PlacementModel.fromJSON(worldDocumentV2ToSceneModelJSON(world));
const before = new Map(
model.placements().placements.map((placement) => [placement.instanceId, placement]),
);
expect(model.move('house_exact', { delta: [7.25, -3.5], scale: 1.75 }).ok).toBe(true);
expect(model.face('house_exact', 42.125).ok).toBe(true);
const group = model.group(['trees#0', 'trees#1'], { name: 'moved-grove', delta: [4, -2] });
expect(group.ok).toBe(true);
expect(model.face('trees#0', 'center').ok).toBe(true);
expect(model.face('trees#1', [40, -10]).ok).toBe(true);
const after = new Map(
model.placements().placements.map((placement) => [placement.instanceId, placement]),
);
expect(after.get('house_exact')!.pos).toEqual([
before.get('house_exact')!.pos[0] + 7.25,
before.get('house_exact')!.pos[1],
before.get('house_exact')!.pos[2] - 3.5,
]);
expect(after.get('house_exact')!.rotYDeg).toBe(42.125);
expect(after.get('house_exact')!.scale).toBe(1.75);
for (const id of ['trees#0', 'trees#1']) {
expect(after.get(id)!.pos).toEqual([
before.get(id)!.pos[0] + 4,
before.get(id)!.pos[1],
before.get(id)!.pos[2] - 2,
]);
}
expect(after.get('trees#0')!.rotYDeg).toBe(
facingToRotY('center', [after.get('trees#0')!.pos[0], after.get('trees#0')!.pos[2]], [0, 0]),
);
expect(after.get('trees#1')!.rotYDeg).toBe(
facingToRotY([40, -10], [after.get('trees#1')!.pos[0], after.get('trees#1')!.pos[2]], [0, 0]),
);
const persisted = model.toJSON();
const house = persisted.statements.find((statement) => statement.alias === 'house_exact');
expect(house?.kind === 'place' && house.exact).toEqual({
pos: after.get('house_exact')!.pos,
rotYDeg: 42.125,
});
expect(
persisted.statements
.filter((statement) => statement.alias === 'trees#0' || statement.alias === 'trees#1')
.every((statement) => statement.group === 'moved-grove'),
).toBe(true);
});
test('uses caller-supplied evaluated placements as the exact migration seam', () => {
const source = v1Model();
const placements = PlacementModel.fromJSON(source).placements().placements;
placements[0] = {
...placements[0]!,
instanceId: 'host-authoritative-id',
pos: [1.234567890123, -2.5, 9.876543210987],
rotYDeg: 123.456789,
};
const world = migrateSceneModelV1ToWorldDocumentV2(source, {
...migrationOptions,
placements,
});
expect(world.objects[0]).toMatchObject({
id: 'host-authoritative-id',
transform: {
position: [1.234567890123, -2.5, 9.876543210987],
rotationYDeg: 123.456789,
uniformScale: 1.125,
},
});
});
test('canonical JSON and SHA-256 are byte-stable and key-order independent', async () => {
const world = migrateSceneModelV1ToWorldDocumentV2(v1Model(), migrationOptions);
const reordered = JSON.parse(JSON.stringify(world)) as Record<string, unknown>;
const reversedTopLevel = Object.fromEntries(Object.entries(reordered).reverse());
const json = canonicalWorldDocumentV2Json(world);
expect(canonicalWorldDocumentV2Json(reversedTopLevel)).toBe(json);
expect(json.endsWith('\n')).toBe(false);
const expected = createHash('sha256').update(json).digest('hex');
expect(await hashWorldDocumentV2(world)).toBe(`sha256:${expected}`);
expect(await hashWorldDocumentV2(world)).toBe(await hashWorldDocumentV2(reversedTopLevel));
const changed = structuredClone(world);
changed.assets[0]!.artifactSha256 = 'a'.repeat(64);
expect(await hashWorldDocumentV2(changed)).not.toBe(await hashWorldDocumentV2(world));
});
test('fails closed on unknown versions, unknown keys, bad refs, duplicate ids, and non-finite numbers', () => {
const world = migrateSceneModelV1ToWorldDocumentV2(v1Model(), migrationOptions);
expect(() => parseWorldDocumentV2({ ...world, schemaVersion: 'kiln.world.v3' })).toThrow();
expect(() => parseWorldDocumentV2({ ...world, unexpected: true })).toThrow();
const badRef = structuredClone(world);
badRef.objects[0]!.assetRefId = 'missing';
expect(safeParseWorldDocumentV2(badRef).success).toBe(false);
const duplicate = structuredClone(world);
duplicate.objects[1]!.id = duplicate.objects[0]!.id;
expect(safeParseWorldDocumentV2(duplicate).success).toBe(false);
const infinite = structuredClone(world);
infinite.objects[0]!.transform.position[0] = Number.POSITIVE_INFINITY;
expect(safeParseWorldDocumentV2(infinite).success).toBe(false);
});
test('rejects unreferenced asset and collision artifacts', () => {
const world = migrateSceneModelV1ToWorldDocumentV2(v1Model(), migrationOptions);
const unusedAsset = structuredClone(world);
unusedAsset.assets.push({
...structuredClone(unusedAsset.assets[0]!),
refId: 'asset:unused',
generationId: 'unused',
});
expect(safeParseWorldDocumentV2(unusedAsset).success).toBe(false);
const unusedCollision = structuredClone(world);
unusedCollision.collisionArtifacts.push({
refId: 'collision:unused',
artifact: {
uri: 'colliders/unused.glb',
sha256: 'b'.repeat(64),
mediaType: 'model/gltf-binary',
},
});
expect(safeParseWorldDocumentV2(unusedCollision).success).toBe(false);
const referencedCollision = structuredClone(unusedCollision);
referencedCollision.objects[0]!.collision = {
policy: 'artifact',
artifactRefId: 'collision:unused',
};
expect(safeParseWorldDocumentV2(referencedCollision).success).toBe(true);
});
test('accepts an empty world and exactly 200 objects, but rejects 201', () => {
const empty = migrateSceneModelV1ToWorldDocumentV2(
{ name: 'Empty', seed: 1, catalog: [], statements: [] },
{ worldId: 'empty', artifactSha256ByGenerationId: {} },
);
expect(empty.assets).toEqual([]);
expect(empty.objects).toEqual([]);
const base = migrateSceneModelV1ToWorldDocumentV2(v1Model(), migrationOptions);
const boundary = structuredClone(base);
boundary.objects = Array.from({ length: 200 }, (_, index) => ({
...structuredClone(base.objects[0]!),
id: `object-${index}`,
}));
boundary.assets = [structuredClone(base.assets[0]!)];
expect(safeParseWorldDocumentV2(boundary).success).toBe(true);
boundary.objects.push({ ...structuredClone(base.objects[0]!), id: 'object-200' });
expect(safeParseWorldDocumentV2(boundary).success).toBe(false);
});
test('reconciles moved objects while preserving retained world-only fields', async () => {
const world = migrateSceneModelV1ToWorldDocumentV2(v1Model(), migrationOptions);
world.objects[0]!.collision = { policy: 'bounds' };
const beforeHash = await hashWorldDocumentV2(world);
const replacements = world.objects.map((object) => {
const asset = world.assets.find((candidate) => candidate.refId === object.assetRefId)!;
return {
id: object.id,
generationId: asset.generationId,
position: object.transform.position,
rotationYDeg: object.transform.rotationYDeg,
uniformScale: object.transform.uniformScale,
};
});
replacements[0] = {
...replacements[0]!,
position: [99, 4, -33],
rotationYDeg: 77.5,
uniformScale: 2,
};
const reconciled = reconcileWorldDocumentV2Objects(world, { objects: replacements });
expect(reconciled.objects.find((object) => object.id === 'house_exact')).toEqual({
...world.objects[0]!,
transform: { position: [99, 4, -33], rotationYDeg: 77.5, uniformScale: 2 },
});
expect(reconciled.environment).toEqual(world.environment);
expect(reconciled.terrain).toEqual(world.terrain);
expect(reconciled.authored).toEqual(world.authored);
expect(reconciled.provenance).toEqual(world.provenance);
expect(await hashWorldDocumentV2(reconciled)).not.toBe(beforeHash);
});
test('reconciles additions and removals with closed asset and collision references', () => {
const world = migrateSceneModelV1ToWorldDocumentV2(v1Model(), migrationOptions);
world.collisionArtifacts.push({
refId: 'collision:house',
artifact: { uri: 'collision/house.glb', sha256: 'c'.repeat(64) },
});
world.objects[0]!.collision = { policy: 'artifact', artifactRefId: 'collision:house' };
const reconciled = reconcileWorldDocumentV2Objects(world, {
objects: [
{
id: 'trees#0',
generationId: 'tree',
position: [20, 0, 0],
rotationYDeg: 0,
uniformScale: 0.85,
},
{
id: 'new-lantern',
generationId: 'lantern',
position: [3, 0, 4],
rotationYDeg: 15,
uniformScale: 1,
},
],
assets: [
{
generationId: 'lantern',
artifactSha256: 'd'.repeat(64),
bounds: { min: [-0.5, 0, -0.5], max: [0.5, 2, 0.5] },
name: 'Lantern',
role: 'prop',
},
],
environment: {
presetId: 'night',
lightingPresetId: 'night-v2',
groundPaint: [],
},
});
expect(reconciled.objects.map((object) => object.id)).toEqual(['new-lantern', 'trees#0']);
expect(reconciled.assets.map((asset) => asset.generationId)).toEqual(['lantern', 'tree']);
expect(reconciled.collisionArtifacts).toEqual([]);
expect(reconciled.environment).toEqual({
presetId: 'night',
lightingPresetId: 'night-v2',
groundPaint: [],
});
expect(reconciled.objects[0]).toMatchObject({
id: 'new-lantern',
role: 'support',
provenance: { sourceStatementId: 'manual:new-lantern' },
});
});
test('reconciliation is input-order independent and artifact-hash sensitive', async () => {
const world = migrateSceneModelV1ToWorldDocumentV2(v1Model(), migrationOptions);
const objects = world.objects.map((object) => ({
id: object.id,
generationId: world.assets.find((asset) => asset.refId === object.assetRefId)!.generationId,
position: object.transform.position,
rotationYDeg: object.transform.rotationYDeg,
uniformScale: object.transform.uniformScale,
}));
const ordered = reconcileWorldDocumentV2Objects(world, { objects });
const reversed = reconcileWorldDocumentV2Objects(world, { objects: [...objects].reverse() });
expect(reversed).toEqual(ordered);
expect(await hashWorldDocumentV2(reversed)).toBe(await hashWorldDocumentV2(ordered));
const house = world.assets.find((asset) => asset.generationId === 'house')!;
const changedHash = reconcileWorldDocumentV2Objects(world, {
objects,
assets: [
{
generationId: house.generationId,
artifactSha256: 'e'.repeat(64),
bounds: house.bounds,
...(house.name ? { name: house.name } : {}),
...(house.tags ? { tags: house.tags } : {}),
...(house.role ? { role: house.role } : {}),
...(house.tier ? { tier: house.tier } : {}),
},
],
});
expect(await hashWorldDocumentV2(changedHash)).not.toBe(await hashWorldDocumentV2(ordered));
});
test('keeps only referenced assets and requires a real hash for each one', () => {
const withUnusedCatalogAsset = v1Model();
withUnusedCatalogAsset.catalog.push({
generationId: 'unused-prop',
bbox: { min: [-1, 0, -1], max: [1, 2, 1] },
role: 'prop',
});
const migrated = migrateSceneModelV1ToWorldDocumentV2(withUnusedCatalogAsset, migrationOptions);
expect(migrated.assets.map((asset) => asset.generationId)).toEqual(['house', 'tree']);
expect(() =>
migrateSceneModelV1ToWorldDocumentV2(v1Model(), {
worldId: 'scene-123',
artifactSha256ByGenerationId: { house: HOUSE_SHA },
}),
).toThrow('missing artifact SHA-256 for generation "tree"');
expect(() =>
migrateSceneModelV1ToWorldDocumentV2(v1Model(), {
worldId: 'scene-123',
artifactSha256ByGenerationId: { house: 'not-a-hash', tree: TREE_SHA },
}),
).toThrow();
});
test('rejects unknown and malformed persisted v1 model shapes before evaluation', () => {
expect(() =>
migrateSceneModelV1ToWorldDocumentV2(
{ ...v1Model(), unknownRoot: true } as unknown as SceneModelJSON,
migrationOptions,
),
).toThrow();
const malformed = v1Model() as unknown as { statements: Array<Record<string, unknown>> };
malformed.statements[0]!.kind = 'unsupported';
expect(() =>
migrateSceneModelV1ToWorldDocumentV2(
malformed as unknown as SceneModelJSON,
migrationOptions,
),
).toThrow();
const nonFinite = v1Model();
nonFinite.statements[0]!.scale = Number.POSITIVE_INFINITY;
expect(() => migrateSceneModelV1ToWorldDocumentV2(nonFinite, migrationOptions)).toThrow();
});
test('rejects duplicate v1 ids and aliases plus dangling asset references', () => {
const duplicateGeneration = v1Model();
duplicateGeneration.catalog.push(structuredClone(duplicateGeneration.catalog[0]!));
expect(() =>
migrateSceneModelV1ToWorldDocumentV2(duplicateGeneration, migrationOptions),
).toThrow();
const duplicateStatement = v1Model();
duplicateStatement.statements[1]!.stmtId = duplicateStatement.statements[0]!.stmtId;
expect(() =>
migrateSceneModelV1ToWorldDocumentV2(duplicateStatement, migrationOptions),
).toThrow();
const duplicateAlias = v1Model();
duplicateAlias.statements[1]!.alias = duplicateAlias.statements[0]!.alias;
expect(() => migrateSceneModelV1ToWorldDocumentV2(duplicateAlias, migrationOptions)).toThrow();
const dangling = v1Model();
dangling.statements[0]!.generationId = 'missing-generation';
expect(() => migrateSceneModelV1ToWorldDocumentV2(dangling, migrationOptions)).toThrow();
});
});