@vgai/engine 0.5.0 → 0.5.2

package/dist/humanoid/bake.operation.js

@@ -1,228 +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(),
-});
-function installNodeThreePolyfills() {
-    const target = globalThis;
-    if (!target['self'])
-        target['self'] = globalThis;
-    if (!target['ProgressEvent']) {
-        target['ProgressEvent'] = class {
-            type;
-            constructor(type, init = {}) {
-                this.type = type;
-                Object.assign(this, init);
-            }
-        };
-    }
-    if (!target['createImageBitmap']) {
-        target['createImageBitmap'] = async () => ({ close() { } });
-    }
-    if (!target['FileReader']) {
-        target['FileReader'] = class {
-            result = null;
-            onloadend = null;
-            readAsArrayBuffer(blob) {
-                void blob.arrayBuffer().then((value) => {
-                    this.result = value;
-                    this.onloadend?.();
-                });
-            }
-            readAsDataURL(blob) {
-                void blob.arrayBuffer().then((value) => {
-                    this.result = `data:${blob.type || 'application/octet-stream'};base64,${Buffer.from(value).toString('base64')}`;
-                    this.onloadend?.();
-                });
-            }
-        };
-    }
-}
-async function resolvePublicFile(projectRoot, path) {
-    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, sourcePath, names, rig) {
-    installNodeThreePolyfills();
-    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;
-        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') };
-}
-async function exportGlb(root, animations) {
-    installNodeThreePolyfills();
-    const result = await new Promise((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 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',
-    mutates: true,
-    supportsDryRun: true,
-    longRunning: true,
-    permission: {
-        risk: 'write',
-        summary: 'Writes or replaces generated model, prefab, and provenance files under public/.',
-    },
-    async impl(input, ctx) {
-        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();
-        }
-    },
-};

package/dist/humanoid/body.d.ts

@@ -1,101 +0,0 @@
-/**
- * The procedural humanoid BODY: entirely procedural three.js geometry
- * (capsules + one pelvis box via `CapsuleGeometry`/`BoxGeometry`, merged with
- * `BufferGeometryUtils.mergeGeometries` into ONE `SkinnedMesh`). No imported
- * mesh anywhere. Promoted from the accepted Phase-1 PoC
- * (`packages/engine/e2e/humanoid-skin-proof/procedural-body.ts`) and
- * parameterized by body dimensions — with all-default dims the output is
- * bit-identical to the PoC body.
- *
- * Skin binding is **analytic per-segment with smooth 2-bone joint blending**:
- * every body part is generated along one bone segment (proximal joint →
- * distal joint, both known a priori from the rest pose), so each vertex's
- * normalized position `t` along the bone axis is exact — no nearest-bone
- * search, no heuristic falloff radius. Vertices in the interior of a segment
- * bind 100% to that segment's bone; vertices inside a blend zone at either
- * end split weight smoothstep-wise with the adjacent bone, reaching 50/50 at
- * (and past) the joint itself. This is the standard cure for the two classic
- * rigid-binding artifacts: gaps/interpenetration at elbows/knees (fixed by
- * the overshoot + 50/50 blend across the joint) and hard shading creases
- * (fixed by the smoothstep ramp). Because the blend zone is derived from the
- * ACTUAL joint positions of the (possibly rescaled) skeleton, weights stay
- * correct as body proportions change. Two influences per vertex is enough
- * for a capsule-limb body; the vertex format still uses the standard 4-wide
- * skinIndex/skinWeight attributes, zero-padded, exactly as GLTF skins do.
- */
-import * as THREE from 'three';
-import type { BuiltSkeleton } from './skeleton';
-/** The head capsule's reference radius — `generate.ts` feeds this (× headSize)
- *  to the skeleton height normalization as the crown padding. */
-export declare const HEAD_CAPSULE_RADIUS: number;
-/** Body dimension multipliers, resolved by `generate.ts` from the params. */
-export interface HumanoidBodyDims {
-    /** The skeleton's uniform height factor — every base metre scales by this. */
-    heightFactor: number;
-    limbThickness: number;
-    torsoGirth: number;
-    headSize: number;
-    hipWidth: number;
-}
-export declare const smoothstep: (x: number) => number;
-/** Blend-zone length as a fraction of a segment (≈10 cm at reference scale,
- *  clamped to 20–50% of the segment) — shared verbatim by the body generator
- *  and `skinToHumanoid` so clothing gets the SAME joint blend as the body. */
-export declare const blendZone: (len: number, heightFactor: number) => number;
-/** One merged-body part's vertex range + the bones its weights may reference —
- *  the segment-adjacency contract the unit tests verify. */
-export interface HumanoidBodyPart {
-    name: string;
-    /** skinIndex values every non-zero-weight influence in the range must use. */
-    boneIndices: readonly number[];
-    vertexStart: number;
-    vertexCount: number;
-}
-export interface HumanoidBody {
-    mesh: THREE.SkinnedMesh;
-    skeleton: THREE.Skeleton;
-    vertexCount: number;
-    parts: readonly HumanoidBodyPart[];
-}
-/**
- * Build the whole body as ONE merged `SkinnedMesh` in the rig root's space
- * (the skeleton's rest pose), and bind it. Callers must have called
- * `updateMatrixWorld(true)` on the armature's parent after adding the bone
- * hierarchy, so every bone's `matrixWorld` is its rest pose —
- * `new THREE.Skeleton(bones)` captures the inverse bind matrices from
- * exactly those.
- */
-export declare function buildHumanoidBody(rig: BuiltSkeleton, dims: HumanoidBodyDims, material?: THREE.Material): HumanoidBody;
-/** One skin-binding segment of the standard body, resolved against a concrete
- *  rest pose: the analytic per-segment data `skinToHumanoid` shares with the
- *  body generator so arbitrary clothing geometry deforms EXACTLY like the
- *  body part underneath it. Not part of the public module surface. */
-export interface HumanoidBindingSegment {
-    /** Primary bone row (the skinIndex value). */
-    bone: number;
-    /** Blend-partner rows near t=0 / t=1 (-1 = rigid end). */
-    proximal: number;
-    distal: number;
-    /** Proximal joint rest position, model-space metres. */
-    p0: THREE.Vector3;
-    /** Unit axis p0→p1 (p1 = distal joint) and the joint-to-joint length. */
-    axis: THREE.Vector3;
-    len: number;
-    /** Normalized blend-zone length (the body's own `blendZone` value). */
-    blend: number;
-    /** The body part's surface radius, metres — nearest-segment selection
-     *  measures distance to the SURFACE so loose clothing picks the part it
-     *  visually covers, not merely the closest bone axis. */
-    radius: number;
-}
-/**
- * Resolve the body's segment map (plus one synthetic rigid pelvis segment —
- * the pelvis box binds 100% to Hips, and belts/skirts must get the same
- * anchor to stay congruent with it) against a concrete rest pose.
- * Parameterized on lookups rather than `BuiltSkeleton` because the compose
- * path recovers rest joints from `Skeleton.boneInverses` (bones may be
- * mid-animation by then), while the generator reads live rest matrices.
- * `jointAt` must return a FRESH Vector3 per call (results are mutated here).
- */
-export declare function computeBindingSegments(jointAt: (name: string) => THREE.Vector3, indexOf: (name: string) => number, dims: HumanoidBodyDims): HumanoidBindingSegment[];
-//# sourceMappingURL=body.d.ts.map

package/dist/humanoid/body.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"body.d.ts","sourceRoot":"","sources":["../../src/humanoid/body.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAuShD;iEACiE;AACjE,eAAO,MAAM,mBAAmB,QACmC,CAAC;AAEpE,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,UAAU,GAAI,GAAG,MAAM,KAAG,MAGtC,CAAC;AAEF;;8EAE8E;AAC9E,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,EAAE,cAAc,MAAM,KAAG,MACJ,CAAC;AAuI3D;4DAC4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC;IACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACpC;AAeD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,gBAAgB,EACtB,QAAQ,CAAC,EAAE,KAAK,CAAC,QAAQ,GACxB,YAAY,CA0Dd;AAID;;;sEAGsE;AACtE,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC;IAClB,yEAAyE;IACzE,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd;;6DAEyD;IACzD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC,OAAO,EACxC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EACjC,IAAI,EAAE,gBAAgB,GACrB,sBAAsB,EAAE,CAwC1B"}