Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

14.6 KB
Raw Blame
/** Bounded Strands tool surface for canonical Composer V2 integration primitives. */
import { type JSONValue, type Tool, tool } from '@strands-agents/sdk';
import { z } from 'zod';
import {
  AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1,
  AUTHORED_COLLIDER_GEOMETRY_V1_SCHEMA_VERSION,
  ColliderCompileError,
  ColliderPolicyV1Schema,
  compileColliderArtifactV1,
  encodeColliderArtifactV1,
  hashColliderArtifactV1,
  type ColliderArtifactV1,
  parseAuthoredColliderGeometryV1,
  type ResolveAuthoredColliderGeometryV1Port,
  createHeightfieldArtifactV1,
  encodeHeightfieldArtifactV1,
  hashHeightfieldArtifactV1,
  type HeightfieldArtifactV1,
  fillWorldPathV2,
  setWorldPathsV2,
  setWorldPresentationV1,
  setWorldSocketsV2,
  setWorldSpawnsV2,
  setWorldTerrainV2,
  setWorldZonesV2,
  snapWorldObjectToSocketV2,
  type WorldDocumentV2,
  PresentationParametersV1Schema,
  parseWorldDocumentV2,
} from '..';

export interface WorldIntegrationToolState {
  world: WorldDocumentV2;
}
export interface MakeWorldIntegrationToolsV2Options {
  state: WorldIntegrationToolState;
  publishHeightfieldArtifact?: (
    artifact: HeightfieldArtifactV1,
    bytes: Uint8Array,
    sha256: string,
  ) => Promise<{ uri: string; mediaType?: string }>;
  publishColliderArtifact?: (
    artifact: ColliderArtifactV1,
    bytes: Uint8Array,
    sha256: `sha256:${string}`,
  ) => Promise<{ uri: string; mediaType?: string }>;
  resolveAuthoredColliderGeometry?: ResolveAuthoredColliderGeometryV1Port;
  onWorldChanged?: (world: WorldDocumentV2) => void;
}

const finite = z.number().finite();
const vec2 = z.tuple([finite, finite]);
const vec3 = z.tuple([finite, finite, finite]);
const id = z.string().min(1).max(256);
const positiveVec2 = z.tuple([finite.positive(), finite.positive()]);

export function makeWorldIntegrationToolsV2(options: MakeWorldIntegrationToolsV2Options): Tool[] {
  const commit = (world: WorldDocumentV2): JSONValue => {
    options.state.world = world;
    options.onWorldChanged?.(world);
    return { ok: true, worldId: world.worldId };
  };
  const guarded = (operation: () => WorldDocumentV2): JSONValue => {
    try {
      return commit(operation());
    } catch (error) {
      return { ok: false, error: error instanceof Error ? error.message : String(error) };
    }
  };

  const setZones: Tool = tool({
    name: 'scene_world_set_zones',
    description:
      'Replace bounded reserved/portal/spawn-clearance zones. Rect halfExtents must be positive.',
    inputSchema: z
      .object({
        zones: z
          .array(
            z
              .object({
                id,
                kind: z.enum(['reserved', 'portal-clearance', 'spawn-clearance']),
                shape: z.discriminatedUnion('type', [
                  z
                    .object({ type: z.literal('rect'), center: vec2, halfExtents: positiveVec2 })
                    .strict(),
                  z
                    .object({ type: z.literal('circle'), center: vec2, radius: finite.positive() })
                    .strict(),
                ]),
              })
              .strict(),
          )
          .max(32),
      })
      .strict(),
    callback: (input) => guarded(() => setWorldZonesV2(options.state.world, input.zones)),
  });
  const setPaths: Tool = tool({
    name: 'scene_world_set_paths',
    description: 'Replace authored navigational paths using world-space X/Y/Z points.',
    inputSchema: z
      .object({
        paths: z
          .array(
            z
              .object({
                id,
                points: z.array(vec3).min(2).max(64),
                halfWidth: finite.positive(),
              })
              .strict(),
          )
          .max(16),
      })
      .strict(),
    callback: (input) => guarded(() => setWorldPathsV2(options.state.world, input.paths)),
  });
  const setSockets: Tool = tool({
    name: 'scene_world_set_sockets',
    description:
      'Replace named anchors/portals with compatibility, capacity, and portal clearance.',
    inputSchema: z
      .object({
        sockets: z
          .array(
            z
              .object({
                id,
                kind: z.enum(['anchor', 'portal']),
                position: vec3,
                rotationYDeg: finite,
                compatibilityTags: z.array(z.string().min(1).max(128)).min(1).max(16),
                capacity: z.number().int().min(1).max(8),
                clearanceRadius: finite.positive().optional(),
              })
              .strict(),
          )
          .max(32),
      })
      .strict(),
    callback: (input) => guarded(() => setWorldSocketsV2(options.state.world, input.sockets)),
  });
  const setSpawns: Tool = tool({
    name: 'scene_world_set_spawns',
    description: 'Replace player/actor spawns, each with a positive clearance radius.',
    inputSchema: z
      .object({
        spawns: z
          .array(
            z
              .object({
                id,
                position: vec3,
                rotationYDeg: finite,
                clearanceRadius: finite.positive(),
              })
              .strict(),
          )
          .max(16),
      })
      .strict(),
    callback: (input) => guarded(() => setWorldSpawnsV2(options.state.world, input.spawns)),
  });
  const setPresentation: Tool = tool({
    name: 'scene_world_set_presentation',
    description:
      'Replace persisted ordered camera/grid/lighting/receipt parameters. Do not send artifactBinding; Engine binds the post-edit world hash. Total requested pixels are capped at 16,777,216.',
    inputSchema: z.object({ presentation: PresentationParametersV1Schema }).strict(),
    callback: (input) =>
      guarded(() => setWorldPresentationV1(options.state.world, input.presentation)),
  });
  const setCollision: Tool = tool({
    name: 'scene_world_set_collision',
    description:
      'Set one object collision policy to none, asset bounds, selected authored GLB mesh nodes, or a deterministic generated bounds-box artifact. Artifact policies require bounded host ports.',
    inputSchema: z.object({ objectId: id, policy: ColliderPolicyV1Schema }).strict(),
    callback: async (input) => {
      try {
        const object = options.state.world.objects.find(
          (candidate) => candidate.id === input.objectId,
        );
        if (!object) return { ok: false, error: `unknown object "${input.objectId}"` } as JSONValue;
        const asset = options.state.world.assets.find(
          (candidate) => candidate.refId === object.assetRefId,
        );
        if (!asset)
          return { ok: false, error: `missing asset for "${input.objectId}"` } as JSONValue;

        if (input.policy.kind === 'none' || input.policy.kind === 'bounds') {
          const objects = options.state.world.objects.map((candidate) =>
            candidate.id === object.id
              ? { ...candidate, collision: { policy: input.policy.kind } }
              : candidate,
          );
          const referenced = new Set(
            objects.flatMap((candidate) =>
              candidate.collision?.policy === 'artifact' ? [candidate.collision.artifactRefId] : [],
            ),
          );
          return commit(
            parseWorldDocumentV2({
              ...options.state.world,
              objects,
              collisionArtifacts: options.state.world.collisionArtifacts.filter((artifact) =>
                referenced.has(artifact.refId),
              ),
            }),
          );
        }

        if (input.policy.kind === 'authored-submesh' && !options.resolveAuthoredColliderGeometry) {
          return {
            ok: false,
            error: 'authored collider geometry resolver is not configured',
          } as JSONValue;
        }
        if (!options.publishColliderArtifact) {
          return { ok: false, error: 'collider artifact publisher is not configured' } as JSONValue;
        }
        const sourceArtifactSha256 = `sha256:${asset.artifactSha256}` as const;
        let artifact: ColliderArtifactV1;
        if (input.policy.kind === 'authored-submesh') {
          const resolved = parseAuthoredColliderGeometryV1(
            await options.resolveAuthoredColliderGeometry!(
              Object.freeze({
                schemaVersion: AUTHORED_COLLIDER_GEOMETRY_V1_SCHEMA_VERSION,
                sourceArtifactSha256,
                transformFrame: 'asset-local',
                nodeNames: Object.freeze([...input.policy.nodeNames]),
                limits: AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1,
              }),
            ),
          );
          if (resolved.sourceArtifactSha256 !== sourceArtifactSha256) {
            throw new ColliderCompileError(
              'COLLIDER_SOURCE_HASH_MISMATCH',
              'resolved collider geometry does not match the selected asset hash',
            );
          }
          const requested = new Set(input.policy.nodeNames);
          const returned = new Set(resolved.submeshes.map((entry) => entry.nodeName));
          const missing = input.policy.nodeNames.filter((nodeName) => !returned.has(nodeName));
          if (missing.length) {
            throw new ColliderCompileError(
              'COLLIDER_AUTHORED_SUBMESH_MISSING',
              `missing authored collider node(s): ${missing.join(', ')}`,
            );
          }
          const unexpected = resolved.submeshes
            .map((entry) => entry.nodeName)
            .filter((nodeName) => !requested.has(nodeName));
          if (unexpected.length) {
            throw new ColliderCompileError(
              'COLLIDER_AUTHORED_SUBMESH_INVALID',
              `resolver returned unrequested collider node(s): ${unexpected.join(', ')}`,
            );
          }
          artifact = compileColliderArtifactV1(input.policy, {
            sourceArtifactSha256,
            bounds: asset.bounds,
            authoredSubmeshes: resolved.submeshes,
          });
        } else {
          artifact = compileColliderArtifactV1(input.policy, {
            sourceArtifactSha256,
            bounds: asset.bounds,
          });
        }
        const bytes = encodeColliderArtifactV1(artifact);
        const sha256 = await hashColliderArtifactV1(artifact);
        const published = await options.publishColliderArtifact(artifact, bytes, sha256);
        const refId = `collision:${sha256.slice('sha256:'.length)}`;
        const objects = options.state.world.objects.map((candidate) =>
          candidate.id === object.id
            ? { ...candidate, collision: { policy: 'artifact' as const, artifactRefId: refId } }
            : candidate,
        );
        const referenced = new Set(
          objects.flatMap((candidate) =>
            candidate.collision?.policy === 'artifact' ? [candidate.collision.artifactRefId] : [],
          ),
        );
        const collisionArtifacts = [
          ...options.state.world.collisionArtifacts.filter(
            (candidate) => candidate.refId !== refId && referenced.has(candidate.refId),
          ),
          {
            refId,
            artifact: {
              uri: published.uri,
              sha256: sha256.slice('sha256:'.length),
              mediaType: published.mediaType ?? 'application/vnd.kiln.collider+json',
            },
          },
        ];
        const result = commit(
          parseWorldDocumentV2({
            ...options.state.world,
            objects,
            collisionArtifacts,
          }),
        ) as Record<string, JSONValue>;
        return { ...result, sha256, bytes: bytes.byteLength } as JSONValue;
      } catch (error) {
        return {
          ok: false,
          error: error instanceof Error ? error.message : String(error),
        } as JSONValue;
      }
    },
  });
  const snap: Tool = tool({
    name: 'scene_world_snap',
    description:
      'Snap one compatible object exactly to a named socket; fails when incompatible or full.',
    inputSchema: z.object({ objectId: id, socketId: id }).strict(),
    callback: (input) => guarded(() => snapWorldObjectToSocketV2(options.state.world, input)),
  });
  const fillPath: Tool = tool({
    name: 'scene_world_fill_path',
    description:
      'Repeat one existing object along a path with deterministic arc-length spacing and tangent facing.',
    inputSchema: z
      .object({
        pathId: id,
        templateObjectId: id,
        idPrefix: z.string().min(1).max(240),
        count: z.number().int().min(1).max(32),
        spacing: finite.positive(),
        startDistance: finite.nonnegative().optional(),
      })
      .strict(),
    callback: (input) => guarded(() => fillWorldPathV2(options.state.world, input)),
  });
  const stampSchema = z.discriminatedUnion('kind', [
    z
      .object({
        kind: z.enum(['road', 'path']),
        points: z.array(vec2).min(2).max(64),
        halfWidth: finite.positive(),
        targetHeight: finite,
      })
      .strict(),
    z
      .object({
        kind: z.literal('pad'),
        center: vec2,
        halfExtents: positiveVec2,
        targetHeight: finite,
      })
      .strict(),
  ]);
  const setHeightfield: Tool = tool({
    name: 'scene_world_set_heightfield',
    description:
      'Generate and bind one bounded seeded heightfield with optional road/path/pad stamps.',
    inputSchema: z
      .object({
        origin: vec2,
        cellSize: finite.positive(),
        width: z.number().int().min(2).max(129),
        height: z.number().int().min(2).max(129),
        baseHeight: finite,
        amplitude: finite.nonnegative(),
        frequency: finite.positive(),
        stamps: z.array(stampSchema).max(16),
      })
      .strict(),
    callback: async (input) => {
      if (!options.publishHeightfieldArtifact)
        return {
          ok: false,
          error: 'heightfield artifact publisher is not configured',
        } as JSONValue;
      try {
        const artifact = createHeightfieldArtifactV1({ ...input, seed: options.state.world.seed });
        const bytes = encodeHeightfieldArtifactV1(artifact);
        const sha256 = await hashHeightfieldArtifactV1(artifact);
        const published = await options.publishHeightfieldArtifact(artifact, bytes, sha256);
        const result = commit(
          setWorldTerrainV2(options.state.world, {
            kind: 'heightfield',
            artifact: {
              uri: published.uri,
              sha256,
              mediaType: published.mediaType ?? 'application/vnd.kiln.heightfield+json',
            },
          }),
        ) as Record<string, JSONValue>;
        return { ...result, sha256, bytes: bytes.byteLength } as JSONValue;
      } catch (error) {
        return {
          ok: false,
          error: error instanceof Error ? error.message : String(error),
        } as JSONValue;
      }
    },
  });
  return [
    setZones,
    setPaths,
    setSockets,
    setSpawns,
    setPresentation,
    setCollision,
    snap,
    fillPath,
    setHeightfield,
  ];
}