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 { z } from 'zod';
import {
assertNoPrototypeKeys,
canonicalContractJson,
sameCanonicalContract,
sha256ContractBytes,
sha256ContractJson,
} from './contract-utils';
import {
parsePresentationDocumentV1,
hashPresentationDocumentV1,
PresentationDocumentV1Schema,
} from './presentation';
import {
hashWorldDocumentV2,
parseWorldDocumentV2,
worldDocumentV2ArtifactReferences,
WorldDocumentV2Schema,
} from './world-document';
export const WORLD_PACKAGE_V2_SCHEMA_VERSION = 'kiln.world-package.v2' as const;
const contentSha256 = z.string().regex(/^sha256:[0-9a-f]{64}$/);
const id = z.string().min(1).max(256);
const portablePath = z
.string()
.min(1)
.max(2048)
.refine(
(path) =>
!path.startsWith('/') &&
!path.includes('\\') &&
!path.includes('?') &&
!path.includes('#') &&
!/^[a-z][a-z0-9+.-]*:/i.test(path) &&
path.split('/').every((segment) => segment.length > 0 && segment !== '.' && segment !== '..'),
'expected a portable package-relative path',
);
const provenanceSchema = z
.object({
worldSource: z.enum(['composer-v1', 'composer-v2', 'manual']),
parentWorldHash: contentSha256.optional(),
objectSources: z
.array(
z
.object({
objectId: id,
sourceStatementId: id,
activeAsset: z
.object({ generationId: id, artifactSha256: contentSha256 })
.strict()
.optional(),
})
.strict(),
)
.max(200),
})
.strict();
const artifactSchema = z
.object({
kind: z.enum(['asset', 'collision', 'heightfield']),
refId: id,
path: portablePath,
sha256: contentSha256,
})
.strict();
export const WorldPackageV2Schema = z
.object({
schemaVersion: z.literal(WORLD_PACKAGE_V2_SCHEMA_VERSION),
world: WorldDocumentV2Schema,
worldSha256: contentSha256,
presentation: PresentationDocumentV1Schema,
presentationSha256: contentSha256,
artifacts: z.array(artifactSchema).max(1024),
runtimePolicy: z.object({ mode: z.literal('static-explore') }).strict(),
provenance: provenanceSchema,
provenanceSha256: contentSha256,
})
.strict()
.superRefine((value, ctx) => {
const artifactPaths = new Set<string>();
for (let index = 0; index < value.artifacts.length; index++) {
const path = value.artifacts[index]!.path;
if (artifactPaths.has(path)) {
ctx.addIssue({
code: 'custom',
path: ['artifacts', index, 'path'],
message: `duplicate package path "${path}"`,
});
}
artifactPaths.add(path);
}
const { artifactBinding, ...presentationParameters } = value.presentation;
if (
!value.world.presentation ||
!sameCanonicalContract(value.world.presentation, presentationParameters)
) {
ctx.addIssue({
code: 'custom',
path: ['presentation'],
message: 'presentation must equal world presentation',
});
}
if (artifactBinding.kind !== 'world' || artifactBinding.sha256 !== value.worldSha256) {
ctx.addIssue({
code: 'custom',
path: ['presentation', 'artifactBinding'],
message: 'presentation artifact binding must equal worldSha256',
});
}
if (!sameCanonicalContract(value.runtimePolicy, value.world.runtimePolicy)) {
ctx.addIssue({
code: 'custom',
path: ['runtimePolicy'],
message: 'runtimePolicy must equal world runtime policy',
});
}
const expectedArtifacts = worldDocumentV2ArtifactReferences(value.world).map((reference) => ({
kind: reference.kind,
refId: reference.refId,
path: reference.packagePath,
sha256: `sha256:${reference.sha256}`,
}));
if (!sameCanonicalContract(value.artifacts, expectedArtifacts)) {
ctx.addIssue({
code: 'custom',
path: ['artifacts'],
message: 'artifacts must equal world artifact closure',
});
}
const expectedProvenance = provenanceOf(value.world);
if (!sameCanonicalContract(value.provenance, expectedProvenance)) {
ctx.addIssue({
code: 'custom',
path: ['provenance'],
message: 'provenance must equal world provenance closure',
});
}
});
export type WorldPackageV2 = z.infer<typeof WorldPackageV2Schema>;
function provenanceOf(world: z.infer<typeof WorldDocumentV2Schema>) {
return {
worldSource: world.provenance.source,
...(world.provenance.parentWorldHash
? { parentWorldHash: world.provenance.parentWorldHash }
: {}),
objectSources: [...world.objects]
.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
.map((object) => ({
objectId: object.id,
sourceStatementId: object.provenance.sourceStatementId,
...(object.provenance.activeAsset
? {
activeAsset: {
generationId: object.provenance.activeAsset.generationId,
artifactSha256: `sha256:${object.provenance.activeAsset.artifactSha256}`,
},
}
: {}),
})),
};
}
export function parseWorldPackageV2(input: unknown): WorldPackageV2 {
assertNoPrototypeKeys(input);
return WorldPackageV2Schema.parse(input);
}
export async function validateWorldPackageV2(input: unknown): Promise<WorldPackageV2> {
const packageDocument = parseWorldPackageV2(input);
const expectedWorldHash = await hashWorldDocumentV2(packageDocument.world);
if (packageDocument.worldSha256 !== expectedWorldHash) {
throw new TypeError(
`worldSha256 mismatch (${packageDocument.worldSha256} != ${expectedWorldHash})`,
);
}
const expectedPresentationHash = await hashPresentationDocumentV1(packageDocument.presentation);
if (packageDocument.presentationSha256 !== expectedPresentationHash) {
throw new TypeError('presentationSha256 mismatch');
}
const expectedProvenanceHash = await sha256ContractJson(packageDocument.provenance);
if (packageDocument.provenanceSha256 !== expectedProvenanceHash) {
throw new TypeError('provenanceSha256 mismatch');
}
return packageDocument;
}
export interface CreateWorldPackageV2Input {
world: unknown;
}
export async function createWorldPackageV2(
input: CreateWorldPackageV2Input,
): Promise<WorldPackageV2> {
const world = parseWorldDocumentV2(input.world);
if (!world.presentation) throw new TypeError('WorldPackageV2 requires world presentation');
const worldSha256 = await hashWorldDocumentV2(world);
const presentation = parsePresentationDocumentV1({
...world.presentation,
artifactBinding: { kind: 'world', sha256: worldSha256 },
});
const provenance = provenanceOf(world);
return validateWorldPackageV2({
schemaVersion: WORLD_PACKAGE_V2_SCHEMA_VERSION,
world,
worldSha256,
presentation,
presentationSha256: await hashPresentationDocumentV1(presentation),
artifacts: worldDocumentV2ArtifactReferences(world).map((reference) => ({
kind: reference.kind,
refId: reference.refId,
path: reference.packagePath,
sha256: `sha256:${reference.sha256}`,
})),
runtimePolicy: world.runtimePolicy,
provenance,
provenanceSha256: await sha256ContractJson(provenance),
});
}
export function canonicalWorldPackageV2Json(input: unknown): string {
return canonicalContractJson(parseWorldPackageV2(input));
}
export function hashWorldPackageV2(input: unknown): Promise<`sha256:${string}`> {
return sha256ContractJson(parseWorldPackageV2(input));
}
/** Verify the exact external artifact bytes that complete the portable package closure. */
export async function validateWorldPackageArtifactBytesV2(
packageInput: unknown,
files: Readonly<Record<string, Uint8Array>>,
): Promise<void> {
const packageDocument = await validateWorldPackageV2(packageInput);
assertNoPrototypeKeys(files, '$files');
const expectedPaths = new Set(packageDocument.artifacts.map((artifact) => artifact.path));
for (const path of Object.keys(files)) {
if (!expectedPaths.has(path)) throw new TypeError(`unexpected package artifact path "${path}"`);
}
for (const artifact of packageDocument.artifacts) {
const bytes = files[artifact.path];
if (!(bytes instanceof Uint8Array)) {
throw new TypeError(`missing package artifact bytes for "${artifact.path}"`);
}
const actual = await sha256ContractBytes(bytes);
if (actual !== artifact.sha256) {
throw new TypeError(`package artifact hash mismatch for "${artifact.path}"`);
}
}
}