@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/src/humanoid/bake.operation.ts

@@ -0,0 +1,326 @@
+/**
+ * Package-contributed Project Command for baking the procedural humanoid into
+ * ordinary project assets. The editor discovers this module through
+ * @vgai/engine's package.json; the editor itself contains no humanoid branch.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import { dirname, resolve, sep } from 'node:path';
+import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { z } from 'zod';
+import { createHumanoidClipLibrary, retargetClipToHumanoid } from './clips';
+import { generateHumanoid } from './generate';
+import { HumanoidParamsSchema } from './schema';
+
+const InputSchema = z.object({
+  name: z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9-_]{0,63}$/)
+    .default('humanoid')
+    .describe(
+      'Stable lowercase asset name used for the generated GLB, prefab, and provenance files.',
+    ),
+  params: HumanoidParamsSchema.default(HumanoidParamsSchema.parse({})).describe(
+    'Procedural body proportions.',
+  ),
+  clipSource: z
+    .string()
+    .optional()
+    .describe(
+      'Optional project-public GLB path containing Mixamo-named clips. When supplied, Idle, Walk, and Run are retargeted and baked into the generated humanoid GLB.',
+    ),
+  clipNames: z
+    .array(z.string())
+    .min(1)
+    .default(['Idle', 'Walk', 'Run'])
+    .describe('Exact standard clip names to retarget from clipSource.'),
+  dryRun: z
+    .boolean()
+    .default(false)
+    .describe('Generate and validate the complete output batch without writing project files.'),
+});
+
+const OutputFileSchema = z.object({
+  path: z.string(),
+  bytes: z.number(),
+  mediaType: z.string().optional(),
+  role: z.enum(['asset', 'prefab', 'provenance', 'other']).optional(),
+});
+
+const ResultSchema = z.object({
+  model: z.string(),
+  prefab: z.string(),
+  provenance: z.string(),
+  vertexCount: z.number(),
+  clips: z.array(z.string()),
+  files: z.array(OutputFileSchema),
+  totalBytes: z.number(),
+  dryRun: z.boolean(),
+});
+
+interface OutputWriter {
+  write(
+    files: ReadonlyArray<{
+      path: string;
+      content: string | Uint8Array;
+      mediaType?: string;
+      role?: 'asset' | 'prefab' | 'provenance' | 'other';
+    }>,
+    options?: { dryRun?: boolean },
+  ): Promise<{
+    files: z.infer<typeof OutputFileSchema>[];
+    totalBytes: number;
+    dryRun: boolean;
+  }>;
+}
+
+interface ProjectOperationContext {
+  projectRoot?: string;
+  projectOutputs?: OutputWriter;
+  signal?: AbortSignal;
+}
+
+const NODE_THREE_POLYFILL_KEYS = [
+  'self',
+  'ProgressEvent',
+  'createImageBitmap',
+  'FileReader',
+] as const;
+let nodeThreePolyfillDepth = 0;
+let nodeThreePreviousDescriptors: Record<
+  (typeof NODE_THREE_POLYFILL_KEYS)[number],
+  PropertyDescriptor | undefined
+> | null = null;
+
+/**
+ * Three's official GLTFLoader/GLTFExporter addons expect a small browser API
+ * surface even when invoked by this declared Node-only project operation.
+ * Install that surface for the duration of overlapping bakes and restore the
+ * editor-server process exactly when the last caller releases it.
+ */
+function installNodeThreePolyfills(): () => void {
+  const target = globalThis as unknown as Record<string, unknown>;
+  if (nodeThreePolyfillDepth === 0) {
+    nodeThreePreviousDescriptors = Object.fromEntries(
+      NODE_THREE_POLYFILL_KEYS.map((key) => [key, Object.getOwnPropertyDescriptor(target, key)]),
+    ) as NonNullable<typeof nodeThreePreviousDescriptors>;
+    if (!target['self']) target['self'] = globalThis;
+    if (!target['ProgressEvent']) {
+      target['ProgressEvent'] = class {
+        readonly type: string;
+        constructor(type: string, init: Record<string, unknown> = {}) {
+          this.type = type;
+          Object.assign(this, init);
+        }
+      };
+    }
+    if (!target['createImageBitmap']) {
+      target['createImageBitmap'] = async () => ({ close() {} });
+    }
+    if (!target['FileReader']) {
+      target['FileReader'] = class {
+        result: string | ArrayBuffer | null = null;
+        onloadend: (() => void) | null = null;
+        readAsArrayBuffer(blob: Blob): void {
+          void blob.arrayBuffer().then((value) => {
+            this.result = value;
+            this.onloadend?.();
+          });
+        }
+        readAsDataURL(blob: Blob): void {
+          void blob.arrayBuffer().then((value) => {
+            this.result = `data:${blob.type || 'application/octet-stream'};base64,${Buffer.from(value).toString('base64')}`;
+            this.onloadend?.();
+          });
+        }
+      };
+    }
+  }
+  nodeThreePolyfillDepth++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    nodeThreePolyfillDepth--;
+    if (nodeThreePolyfillDepth !== 0 || !nodeThreePreviousDescriptors) return;
+    for (const key of NODE_THREE_POLYFILL_KEYS) {
+      const descriptor = nodeThreePreviousDescriptors[key];
+      if (descriptor) Object.defineProperty(target, key, descriptor);
+      else delete target[key];
+    }
+    nodeThreePreviousDescriptors = null;
+  };
+}
+
+async function resolvePublicFile(projectRoot: string, path: string): Promise<string> {
+  const relativePath = path.replace(/^\//, '');
+  const publicRoot = await realpath(resolve(projectRoot, 'public'));
+  const candidate = await realpath(resolve(publicRoot, relativePath));
+  if (candidate !== publicRoot && !candidate.startsWith(`${publicRoot}${sep}`)) {
+    throw new Error(`clipSource must resolve inside the project's public/ directory: ${path}`);
+  }
+  return candidate;
+}
+
+async function loadRetargetedClips(
+  projectRoot: string,
+  sourcePath: string,
+  names: string[],
+  rig: ReturnType<typeof generateHumanoid>,
+) {
+  const releasePolyfills = installNodeThreePolyfills();
+  try {
+    const absolute = await resolvePublicFile(projectRoot, sourcePath);
+    const bytes = await readFile(absolute);
+    const arrayBuffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    const gltf = await new GLTFLoader().parseAsync(arrayBuffer, `${dirname(absolute)}${sep}`);
+    const library = createHumanoidClipLibrary(gltf.animations);
+    const clips = names.map((name) => {
+      const clip = retargetClipToHumanoid(library.get(name), rig);
+      clip.name = name;
+      return clip;
+    });
+    gltf.scene.traverse((object) => {
+      const mesh = object as typeof object & {
+        geometry?: { dispose(): void };
+        material?: { dispose(): void } | Array<{ dispose(): void }>;
+      };
+      mesh.geometry?.dispose();
+      for (const material of Array.isArray(mesh.material)
+        ? mesh.material
+        : mesh.material
+          ? [mesh.material]
+          : []) {
+        material.dispose();
+      }
+    });
+    return { clips, sourceSha256: createHash('sha256').update(bytes).digest('hex') };
+  } finally {
+    releasePolyfills();
+  }
+}
+
+async function exportGlb(
+  root: ReturnType<typeof generateHumanoid>['root'],
+  animations: Awaited<ReturnType<typeof loadRetargetedClips>>['clips'],
+): Promise<Uint8Array> {
+  const releasePolyfills = installNodeThreePolyfills();
+  try {
+    const result = await new Promise<ArrayBuffer>((resolveResult, reject) => {
+      new GLTFExporter().parse(
+        root,
+        (value) => {
+          if (value instanceof ArrayBuffer) resolveResult(value);
+          else reject(new Error('GLTFExporter returned JSON while binary output was requested.'));
+        },
+        reject,
+        {
+          binary: true,
+          animations,
+          onlyVisible: false,
+        },
+      );
+    });
+    return new Uint8Array(result);
+  } finally {
+    releasePolyfills();
+  }
+}
+
+export const operation = {
+  name: 'project.humanoid.bake',
+  summary: 'Bake a procedural humanoid into an ordinary GLB asset and prefab.',
+  description:
+    'Generates VGAI’s skinned procedural humanoid from body parameters. Optionally retargets ' +
+    'Mixamo-named clips from a project-public GLB, then atomically writes the generated GLB, ' +
+    'a normal .prefab.json referencing it, and reproducibility provenance. Use the prefab as ' +
+    'the authored scene object; do not regenerate the visible body every gameplay run. The ' +
+    'baked body keeps the multicolored engineering-reference material: it is not a styled ' +
+    'production character. A prominent player character should receive an intentional, ' +
+    'project-owned material/composition treatment unless that reference look is deliberate.',
+  input: InputSchema,
+  result: ResultSchema,
+  errors: [],
+  requires: { project: true },
+  host: 'node' as const,
+  mutates: true,
+  supportsDryRun: true,
+  longRunning: true,
+  permission: {
+    risk: 'write' as const,
+    summary: 'Writes or replaces generated model, prefab, and provenance files under public/.',
+  },
+  async impl(input: z.infer<typeof InputSchema>, ctx: ProjectOperationContext) {
+    if (!ctx.projectRoot || !ctx.projectOutputs) {
+      throw new Error('project.humanoid.bake requires a project root and generated-output writer.');
+    }
+    if (ctx.signal?.aborted) throw new Error('project.humanoid.bake was cancelled.');
+
+    const rig = generateHumanoid(input.params);
+    try {
+      const loaded = input.clipSource
+        ? await loadRetargetedClips(ctx.projectRoot, input.clipSource, input.clipNames, rig)
+        : { clips: [], sourceSha256: null };
+      const glb = await exportGlb(rig.root, loaded.clips);
+      const base = input.name;
+      const model = `public/models/generated/${base}.glb`;
+      const prefab = `public/prefabs/generated/${base}.prefab.json`;
+      const provenance = `public/models/generated/${base}.provenance.json`;
+      const modelUrl = `/models/generated/${base}.glb`;
+      const prefabDocument = {
+        version: 1,
+        name: base,
+        root: {
+          name: base,
+          mesh: { type: 'gltf', src: modelUrl },
+          ...(loaded.clips.length > 0 ? { animation: {} } : {}),
+          shadow: { enabled: true },
+        },
+      };
+      const provenanceDocument = {
+        version: 1,
+        generator: '@vgai/engine:project.humanoid.bake',
+        params: rig.params,
+        clipSource: input.clipSource ?? null,
+        clipSourceSha256: loaded.sourceSha256,
+        clips: loaded.clips.map((clip) => clip.name),
+        modelSha256: createHash('sha256').update(glb).digest('hex'),
+      };
+      const output = await ctx.projectOutputs.write(
+        [
+          {
+            path: model,
+            content: glb,
+            mediaType: 'model/gltf-binary',
+            role: 'asset',
+          },
+          {
+            path: prefab,
+            content: `${JSON.stringify(prefabDocument, null, 2)}\n`,
+            mediaType: 'application/json',
+            role: 'prefab',
+          },
+          {
+            path: provenance,
+            content: `${JSON.stringify(provenanceDocument, null, 2)}\n`,
+            mediaType: 'application/json',
+            role: 'provenance',
+          },
+        ],
+        { dryRun: input.dryRun },
+      );
+      return {
+        model,
+        prefab,
+        provenance,
+        vertexCount: rig.vertexCount,
+        clips: loaded.clips.map((clip) => clip.name),
+        ...output,
+      };
+    } finally {
+      rig.dispose();
+    }
+  },
+};