@vgai/engine 0.4.0 → 0.4.1

package/tools/humanoid-bake.tool.ts

@@ -0,0 +1,274 @@
+/**
+ * Package-contributed project tool 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 { 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 '../src/humanoid/clips';
+import { generateHumanoid } from '../src/humanoid/generate';
+import { HumanoidParamsSchema } from '../src/humanoid/schema';
+
+export const HumanoidBakeInputSchema = 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 and prefab 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(),
+});
+
+export const HumanoidBakeResultSchema = z.object({
+  model: z.string(),
+  prefab: z.string(),
+  provenanceOperationId: z.string().optional(),
+  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;
+    provenanceOperationId?: string;
+  }>;
+}
+
+interface ProjectToolContext {
+  projectRoot?: string;
+  projectOutputs?: OutputWriter;
+  signal?: AbortSignal;
+}
+
+const nodeThreePolyfillKeys = ['self', 'ProgressEvent', 'createImageBitmap', 'FileReader'] as const;
+
+function installNodeThreePolyfills(): () => void {
+  const target = globalThis as unknown as Record<string, unknown>;
+  const previous = new Map(
+    nodeThreePolyfillKeys.map((key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)]),
+  );
+  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?.();
+        });
+      }
+    };
+  }
+  return () => {
+    for (const key of nodeThreePolyfillKeys) {
+      const descriptor = previous.get(key);
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  };
+}
+
+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 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 };
+}
+
+async function exportGlb(
+  root: ReturnType<typeof generateHumanoid>['root'],
+  animations: Awaited<ReturnType<typeof loadRetargetedClips>>['clips'],
+): Promise<Uint8Array> {
+  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);
+}
+
+export const tool = {
+  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, with automatic project 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: HumanoidBakeInputSchema,
+  result: HumanoidBakeResultSchema,
+  errors: [],
+  requires: { project: true },
+  host: 'node' as const,
+  mutates: true,
+  supportsDryRun: true,
+  longRunning: true,
+  permission: {
+    risk: 'write' as const,
+    summary: 'Writes or replaces a generated model and prefab under public/.',
+  },
+  async impl(input: z.infer<typeof HumanoidBakeInputSchema>, ctx: ProjectToolContext) {
+    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);
+    const restoreNodeGlobals = installNodeThreePolyfills();
+    try {
+      const loaded = input.clipSource
+        ? await loadRetargetedClips(ctx.projectRoot, input.clipSource, input.clipNames, rig)
+        : { clips: [] };
+      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 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 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',
+          },
+        ],
+        { dryRun: input.dryRun },
+      );
+      return {
+        model,
+        prefab,
+        vertexCount: rig.vertexCount,
+        clips: loaded.clips.map((clip) => clip.name),
+        ...output,
+      };
+    } finally {
+      rig.dispose();
+      restoreNodeGlobals();
+    }
+  },
+};

package/src/humanoid/bake.operation.ts

@@ -1,326 +0,0 @@
-/**
- * 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();
-    }
-  },
-};