@vgai/engine 0.5.0-canary.20260719.0 → 0.5.0

package/dist/humanoid/schema.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Authorable body-type parameters for the procedural humanoid generator
+ * (`generateHumanoid`). Same posture as the other engine Zod schemas: every
+ * field carries `.describe()`, and the object is `.strict()` so a typo'd
+ * param fails loudly at parse instead of silently generating the default
+ * body.
+ *
+ * These params are a CODE-API schema (validated by `generateHumanoid` the
+ * way `GameComponent.schema` params are), not a fetched-file format — they
+ * are deliberately NOT wired into `scripts/generate-schema.ts`, whose six
+ * outputs are all on-disk file formats. If a scene-authorable humanoid
+ * entity lands later, that wiring (plus a consumption-map entry) happens
+ * then.
+ *
+ * All multipliers are relative to the reference rig (the vendored Mixamo
+ * soldier's proportions, ~1.83 m). 1 = reference. The generator keeps feet
+ * grounded and skin weights correct across the whole documented range.
+ */
+import { z } from 'zod';
+export declare const HumanoidParamsSchema: z.ZodObject<{
+    height: z.ZodOptional<z.ZodNumber>;
+    legLength: z.ZodDefault<z.ZodNumber>;
+    armLength: z.ZodDefault<z.ZodNumber>;
+    torsoLength: z.ZodDefault<z.ZodNumber>;
+    shoulderWidth: z.ZodDefault<z.ZodNumber>;
+    hipWidth: z.ZodDefault<z.ZodNumber>;
+    headSize: z.ZodDefault<z.ZodNumber>;
+    limbThickness: z.ZodDefault<z.ZodNumber>;
+    torsoGirth: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/** Authorable input shape — every field optional. */
+export type HumanoidParams = z.input<typeof HumanoidParamsSchema>;
+/** Post-parse shape — defaults applied (only `height` stays optional). */
+export type ResolvedHumanoidParams = z.output<typeof HumanoidParamsSchema>;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/humanoid/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,oBAAoB;;;;;;;;;;kBAiFtB,CAAC;AAEZ,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,0EAA0E;AAC1E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/humanoid/schema.js

@@ -0,0 +1,87 @@
+/**
+ * Authorable body-type parameters for the procedural humanoid generator
+ * (`generateHumanoid`). Same posture as the other engine Zod schemas: every
+ * field carries `.describe()`, and the object is `.strict()` so a typo'd
+ * param fails loudly at parse instead of silently generating the default
+ * body.
+ *
+ * These params are a CODE-API schema (validated by `generateHumanoid` the
+ * way `GameComponent.schema` params are), not a fetched-file format — they
+ * are deliberately NOT wired into `scripts/generate-schema.ts`, whose six
+ * outputs are all on-disk file formats. If a scene-authorable humanoid
+ * entity lands later, that wiring (plus a consumption-map entry) happens
+ * then.
+ *
+ * All multipliers are relative to the reference rig (the vendored Mixamo
+ * soldier's proportions, ~1.83 m). 1 = reference. The generator keeps feet
+ * grounded and skin weights correct across the whole documented range.
+ */
+import { z } from 'zod';
+export const HumanoidParamsSchema = z
+    .object({
+    height: z
+        .number()
+        .min(0.3)
+        .max(4)
+        .optional()
+        .describe('Target standing height in metres, measured to the crown of the head. Omit to keep ' +
+        'the natural height implied by the proportion multipliers (the reference rig is ' +
+        '~1.83 m). All body dimensions scale uniformly to hit this, so proportions are ' +
+        'controlled by the multipliers and overall size by this one number.'),
+    legLength: z
+        .number()
+        .min(0.5)
+        .max(2)
+        .default(1)
+        .describe('Thigh + shin length multiplier (1 = reference). The pelvis rest height follows ' +
+        'automatically so the feet stay grounded — long legs raise the hips, short legs ' +
+        'lower them.'),
+    armLength: z
+        .number()
+        .min(0.5)
+        .max(2)
+        .default(1)
+        .describe('Upper-arm + forearm length multiplier (1 = reference).'),
+    torsoLength: z
+        .number()
+        .min(0.5)
+        .max(2)
+        .default(1)
+        .describe('Spine + neck length multiplier (1 = reference) — a longer or shorter trunk.'),
+    shoulderWidth: z
+        .number()
+        .min(0.5)
+        .max(2)
+        .default(1)
+        .describe('Shoulder breadth multiplier (1 = reference): scales the lateral shoulder-root offsets ' +
+        'and the clavicles.'),
+    hipWidth: z
+        .number()
+        .min(0.5)
+        .max(2)
+        .default(1)
+        .describe('Hip/pelvis breadth multiplier (1 = reference): scales the lateral upper-leg root ' +
+        'offsets and the pelvis block width.'),
+    headSize: z
+        .number()
+        .min(0.5)
+        .max(2)
+        .default(1)
+        .describe('Head + neck size multiplier (1 = reference). Larger heads read younger/stylized — ' +
+        'child-proportioned characters pair headSize ≈ 1.3–1.6 with a small height.'),
+    limbThickness: z
+        .number()
+        .min(0.4)
+        .max(2.5)
+        .default(1)
+        .describe('Arm and leg capsule radius multiplier (1 = reference) — slim (≈0.7) to heavyset ' +
+        '(≈1.5). Feet keep their reference radius so ground contact never sinks.'),
+    torsoGirth: z
+        .number()
+        .min(0.4)
+        .max(2.5)
+        .default(1)
+        .describe('Torso/pelvis bulk multiplier (1 = reference): scales the torso capsule radii and the ' +
+        'pelvis block depth — the main "build" control (slim vs heavy trunk).'),
+})
+    .strict();

package/dist/humanoid/skeleton.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The engine's STANDARD humanoid skeleton — Mixamo naming + the Mixamo rest
+ * pose — built at runtime ENTIRELY from `THREE.Bone` (no imported mesh, no
+ * loader). Promoted from the accepted Phase-1 feasibility PoC
+ * (`packages/engine/e2e/humanoid-skin-proof/`), which proved that a skeleton
+ * with these names and this rest pose plays standard Mixamo-named clips.
+ *
+ * Naming standard: **Mixamo** (`mixamorigHips`, `mixamorigSpine`, …) — the
+ * de-facto interchange standard for free humanoid clip libraries, and the
+ * naming of the repo's vendored clip source
+ * (`examples/rts/public/models/Soldier.glb`). Names are the
+ * post-`PropertyBinding.sanitizeNodeName` form (`mixamorig:Hips` →
+ * `mixamorigHips`), i.e. the names GLTFLoader gives clip tracks;
+ * `humanoid/clips.ts` maps the other spellings (`mixamorig:` / `mixamorig_` /
+ * bare) onto these.
+ *
+ * Rest pose: the reference rig's own T-pose. The table below is pure DATA —
+ * per-bone local translation (cm, the rig's native Mixamo unit) + local rest
+ * quaternion — extracted ONCE from Soldier.glb's node hierarchy (see the
+ * provenance note above the table). At runtime nothing is loaded:
+ * `buildHumanoidSkeleton` composes plain `THREE.Bone`s from this table.
+ *
+ * Body-type parameterization: `scaleSkeletonDef` rescales the table's
+ * translations (never the rest rotations) from authored `HumanoidParams` —
+ * per-segment length multipliers, lateral width multipliers, and a final
+ * uniform height normalization — then re-grounds the hips so the feet keep
+ * the reference rig's ground clearance. See that function's comment for the
+ * exact clip-compatibility contract this preserves.
+ */
+import * as THREE from 'three';
+import type { ResolvedHumanoidParams } from './schema';
+/** One bone: sanitized Mixamo name, parent row index (-1 = root), local
+ *  rest translation [x,y,z] in the rig's native cm units, local rest
+ *  quaternion [x,y,z,w]. */
+export type BoneDef = readonly [
+    name: string,
+    parentIndex: number,
+    translation: readonly [number, number, number],
+    rotation: readonly [number, number, number, number]
+];
+export declare const MIXAMO_SKELETON_DEF: readonly BoneDef[];
+/** The hierarchy root bone's canonical name. */
+export declare const HUMANOID_HIPS_BONE = "mixamorigHips";
+/** The source rig's armature transform ("Character" node in Soldier.glb):
+ *  Mixamo exports Z-up centimetres; this maps the rig into the scene's
+ *  Y-up metres. Applied to the Group the root bone is parented under. */
+export declare const ARMATURE_ROTATION_X: number;
+export declare const ARMATURE_SCALE = 0.01;
+export interface BuiltSkeleton {
+    /** `mixamorigHips` — the hierarchy root. */
+    root: THREE.Bone;
+    /** All bones in `MIXAMO_SKELETON_DEF` row order (this order defines skinIndex values). */
+    bones: THREE.Bone[];
+    byName: Map<string, THREE.Bone>;
+}
+/** Build the standard humanoid bone hierarchy from the pure-data table —
+ *  plain `THREE.Bone`s wired parent→child with the source rest pose. */
+export declare function buildHumanoidSkeleton(defs?: readonly BoneDef[]): BuiltSkeleton;
+/** Wrap a built bone hierarchy in the standard armature group (the Z-up-cm →
+ *  Y-up-m transform every def-table translation is authored against). */
+export declare function createArmatureGroup(rig: BuiltSkeleton): THREE.Group;
+export interface ScaledSkeletonDef {
+    /** The rescaled bone table — feed to `buildHumanoidSkeleton`. */
+    defs: readonly BoneDef[];
+    /** The uniform factor applied to EVERY dimension at the end (1 when
+     *  `params.height` is omitted). Body geometry radii must scale by this
+     *  so proportions survive the height normalization. */
+    heightFactor: number;
+    /** Realized standing height, metres, measured to the head-top joint plus
+     *  `crownPadding` (the body's head-capsule radius). */
+    height: number;
+    /** |scaled hips rest translation| / |reference hips rest translation| —
+     *  the factor `clips.ts` multiplies hips `.position` tracks by, so root
+     *  motion authored for the reference rig lands at this rig's hip height. */
+    hipsPositionScale: number;
+}
+/**
+ * Rescale the reference skeleton table for a body type.
+ *
+ * Order of operations (all in the table's native Z-up cm space):
+ *   1. Per-group segment-length / lateral-width multipliers (never the hips
+ *      row, never any rest rotation).
+ *   2. Re-ground: shift the hips rest translation so the lowest foot joint
+ *      keeps the REFERENCE rig's ground clearance (longer legs raise the
+ *      pelvis, shorter legs lower it — feet never float or sink).
+ *   3. Height normalization: if `params.height` is set, uniformly scale every
+ *      translation so head-top + `crownPadding` lands exactly on it.
+ *
+ * With all-default params every step is an exact no-op (multiplies by 1.0,
+ * adds 0.0), so the default rig is bit-identical to the reference table —
+ * that is what keeps the Phase-1 PoC fixture's committed render valid.
+ *
+ * CLIP COMPATIBILITY (the reviewer-flagged trap): animation clips carry
+ * per-bone `.position` tracks baked for the SOURCE rig's segment lengths.
+ * Played raw on a rescaled skeleton they would snap limbs back to source
+ * proportions. The contract here is split with `clips.ts`: this function
+ * only rescales REST translations and reports `hipsPositionScale`;
+ * `retargetClipToHumanoid` drops every non-hips translation track (bones
+ * keep these rest translations) and remaps the hips track by that factor —
+ * the standard humanoid-retarget policy.
+ */
+export declare function scaleSkeletonDef(params: ResolvedHumanoidParams, crownPadding: number): ScaledSkeletonDef;
+//# sourceMappingURL=skeleton.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skeleton.d.ts","sourceRoot":"","sources":["../../src/humanoid/skeleton.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAEvD;;4BAE4B;AAC5B,MAAM,MAAM,OAAO,GAAG,SAAS;IAC7B,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,MAAM;IACnB,WAAW,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;IAC9C,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;CACpD,CAAC;AAiBF,eAAO,MAAM,mBAAmB,EAAE,SAAS,OAAO,EAkEjD,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD;;yEAEyE;AACzE,eAAO,MAAM,mBAAmB,QAAe,CAAC;AAChD,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC;IACjB,0FAA0F;IAC1F,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IACpB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;CACjC;AAED;wEACwE;AACxE,wBAAgB,qBAAqB,CACnC,IAAI,GAAE,SAAS,OAAO,EAAwB,GAC7C,aAAa,CAcf;AAED;yEACyE;AACzE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,aAAa,GAAG,KAAK,CAAC,KAAK,CAOnE;AAuED,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;IACzB;;2DAEuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB;2DACuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf;;gFAE4E;IAC5E,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,sBAAsB,EAC9B,YAAY,EAAE,MAAM,GACnB,iBAAiB,CAyDnB"}

package/dist/humanoid/skeleton.js

@@ -0,0 +1,289 @@
+/**
+ * The engine's STANDARD humanoid skeleton — Mixamo naming + the Mixamo rest
+ * pose — built at runtime ENTIRELY from `THREE.Bone` (no imported mesh, no
+ * loader). Promoted from the accepted Phase-1 feasibility PoC
+ * (`packages/engine/e2e/humanoid-skin-proof/`), which proved that a skeleton
+ * with these names and this rest pose plays standard Mixamo-named clips.
+ *
+ * Naming standard: **Mixamo** (`mixamorigHips`, `mixamorigSpine`, …) — the
+ * de-facto interchange standard for free humanoid clip libraries, and the
+ * naming of the repo's vendored clip source
+ * (`examples/rts/public/models/Soldier.glb`). Names are the
+ * post-`PropertyBinding.sanitizeNodeName` form (`mixamorig:Hips` →
+ * `mixamorigHips`), i.e. the names GLTFLoader gives clip tracks;
+ * `humanoid/clips.ts` maps the other spellings (`mixamorig:` / `mixamorig_` /
+ * bare) onto these.
+ *
+ * Rest pose: the reference rig's own T-pose. The table below is pure DATA —
+ * per-bone local translation (cm, the rig's native Mixamo unit) + local rest
+ * quaternion — extracted ONCE from Soldier.glb's node hierarchy (see the
+ * provenance note above the table). At runtime nothing is loaded:
+ * `buildHumanoidSkeleton` composes plain `THREE.Bone`s from this table.
+ *
+ * Body-type parameterization: `scaleSkeletonDef` rescales the table's
+ * translations (never the rest rotations) from authored `HumanoidParams` —
+ * per-segment length multipliers, lateral width multipliers, and a final
+ * uniform height normalization — then re-grounds the hips so the feet keep
+ * the reference rig's ground clearance. See that function's comment for the
+ * exact clip-compatibility contract this preserves.
+ */
+import * as THREE from 'three';
+/**
+ * Provenance: generated from `examples/rts/public/models/Soldier.glb`
+ * (the three.js example Mixamo soldier vendored by the RTS example) by
+ * parsing the GLB JSON chunk and walking `skins[0].joints[0]`'s node
+ * subtree — 65 bones, covering all 52 nodes the GLB's Idle/Run/TPose/Walk
+ * clips animate. Extraction (node):
+ *
+ *   const json = JSON.parse(glb.slice(20, 20 + glb.readUInt32LE(12)));
+ *   walk(hipsNode, n => [name(n).replace(/[\[\]\.:\/]/g, ''), parentRow,
+ *                        n.translation ?? [0,0,0], n.rotation ?? [0,0,0,1]]);
+ */
+// The rig's ±90° rest rotations serialize as ~0.7071 in the GLB; Math.SQRT1_2
+// is the exact intent.
+const R2 = Math.SQRT1_2;
+export const MIXAMO_SKELETON_DEF = [
+    ['mixamorigHips', -1, [-0.1602, 1.147488, 106.130768], [0, R2, R2, 0]],
+    ['mixamorigSpine', 0, [-0.038121, 9.490517, -1.392063], [0, 0, 0, 1]],
+    ['mixamorigSpine1', 1, [-0.044231, 11.072289, -1.624071], [0, 0, 0, 1]],
+    ['mixamorigSpine2', 2, [-0.050549, 12.654045, -1.856082], [0, 0, 0, 1]],
+    ['mixamorigNeck', 3, [-0.056868, 14.235764, -2.088092], [0, 0, 0, 1]],
+    ['mixamorigHead', 4, [0, 3.280212, 0.313332], [0, 0, 0, 1]],
+    ['mixamorigHeadTop_End', 5, [0, 25.653503, 2.450463], [0, 0, 0, 1]],
+    ['mixamorigLeftShoulder', 3, [6.728773, 11.756622, -2.05846], [R2, R2, 0, 0]],
+    ['mixamorigLeftArm', 7, [-3.178758, 14.094679, -0.059263], [0, 0, 0, 1]],
+    ['mixamorigLeftForeArm', 8, [0.000015, 23.160294, 0], [0, 0, 0, 1]],
+    ['mixamorigLeftHand', 9, [0.000036, 24.07176, 0.000015], [0, 0, 0, 1]],
+    ['mixamorigLeftHandThumb1', 10, [-1.925056, 4.173385, -1.510903], [0, 0, 0, 1]],
+    ['mixamorigLeftHandThumb2', 11, [-1.730873, 2.998001, -1.730855], [0, 0, 0, 1]],
+    ['mixamorigLeftHandThumb3', 12, [-2.106666, 3.648872, -2.106638], [0, 0, 0, 1]],
+    ['mixamorigLeftHandThumb4', 13, [-1.712988, 2.967014, -1.712967], [0, 0, 0, 1]],
+    ['mixamorigLeftHandIndex1', 10, [-0.395972, 14.669356, -2.855875], [0, 0, 0, 1]],
+    ['mixamorigLeftHandIndex2', 15, [-0.000021, 3.24861, -0.000036], [0, 0, 0, 1]],
+    ['mixamorigLeftHandIndex3', 16, [0.000013, 2.659588, -0.000042], [0, 0, 0, 1]],
+    ['mixamorigLeftHandIndex4', 17, [0.000012, 3.633183, -0.00002], [0, 0, 0, 1]],
+    ['mixamorigLeftHandMiddle1', 10, [0.000009, 14.409812, -0.000004], [0, 0, 0, 1]],
+    ['mixamorigLeftHandMiddle2', 19, [-0.000006, 3.25907, -0.000035], [0, 0, 0, 1]],
+    ['mixamorigLeftHandMiddle3', 20, [-0.000003, 2.639858, -0.000025], [0, 0, 0, 1]],
+    ['mixamorigLeftHandMiddle4', 21, [-0.000006, 3.673858, -0.000035], [0, 0, 0, 1]],
+    ['mixamorigLeftHandRing1', 10, [0.318856, 13.191451, 3.305259], [0, 0, 0, 1]],
+    ['mixamorigLeftHandRing2', 23, [-0.000007, 2.717635, -0.000018], [0, 0, 0, 1]],
+    ['mixamorigLeftHandRing3', 24, [0.000012, 2.134457, 0.000041], [0, 0, 0, 1]],
+    ['mixamorigLeftHandRing4', 25, [0, 2.786875, -0.000016], [0, 0, 0, 1]],
+    ['mixamorigLeftHandPinky1', 10, [-0.521934, 11.636352, 5.613723], [0, 0, 0, 1]],
+    ['mixamorigLeftHandPinky2', 27, [-0.000007, 1.559371, 0], [0.000002, -0.000002, 0, 1]],
+    ['mixamorigLeftHandPinky3', 28, [0.000001, 1.540605, -0.000013], [-0.000002, 0.000002, 0, 1]],
+    ['mixamorigLeftHandPinky4', 29, [-0.000003, 1.668713, 0], [-0.000002, 0.000002, 0.000005, 1]],
+    ['mixamorigRightShoulder', 3, [-6.823778, 11.756622, -2.117723], [0, 0, R2, R2]],
+    ['mixamorigRightArm', 31, [-3.183563, 14.057526, -0.05926], [0, 0, 0, 1]],
+    ['mixamorigRightForeArm', 32, [0, 23.1602, 0], [0, 0, 0, 1]],
+    ['mixamorigRightHand', 33, [-0.000015, 24.14341, -0.000017], [0, 0, 0, 1]],
+    ['mixamorigRightHandThumb1', 34, [-2.027328, 4.192596, 1.472372], [0, 0, 0, 1]],
+    ['mixamorigRightHandThumb2', 35, [-1.747421, 3.026642, 1.747453], [0, 0, 0, 1]],
+    ['mixamorigRightHandThumb3', 36, [-2.123373, 3.677785, 2.1234], [0, 0, 0, 1]],
+    ['mixamorigRightHandThumb4', 37, [-1.693868, 2.933862, 1.693906], [0, 0, 0, 1]],
+    ['mixamorigRightHandIndex1', 34, [-0.40802, 14.636856, 3.083014], [0, 0, 0, 1]],
+    ['mixamorigRightHandIndex2', 39, [0, 3.21624, 0.000026], [0, 0, 0, 1]],
+    ['mixamorigRightHandIndex3', 40, [0.000015, 2.638268, 0.000045], [0, 0, 0, 1]],
+    ['mixamorigRightHandIndex4', 41, [0, 3.65332, 0.000027], [0, 0, 0, 1]],
+    ['mixamorigRightHandMiddle1', 34, [0.000031, 14.530449, -0.000024], [0, 0, 0, 1]],
+    ['mixamorigRightHandMiddle2', 43, [0, 3.12674, 0], [0, 0, 0, 1]],
+    ['mixamorigRightHandMiddle3', 44, [0.000008, 2.672478, 0.000014], [0, 0, 0, 1]],
+    ['mixamorigRightHandMiddle4', 45, [-0.042618, 3.130852, 0.057592], [0, 0, 0, 1]],
+    ['mixamorigRightHandRing1', 34, [0.19577, 12.771111, -2.96601], [0, 0, 0, 1]],
+    ['mixamorigRightHandRing2', 47, [0.000015, 2.512802, -0.000039], [0, 0, 0, 1]],
+    ['mixamorigRightHandRing3', 48, [-0.000015, 2.197067, 0.000041], [0, 0, 0, 1]],
+    ['mixamorigRightHandRing4', 49, [0, 3.068436, 0], [0, 0, 0, 1]],
+    ['mixamorigRightHandPinky1', 34, [-0.461517, 11.750786, -5.650592], [0, 0, 0, 1]],
+    ['mixamorigRightHandPinky2', 51, [-0.000015, 1.67952, 0.000027], [0, 0, 0, 1]],
+    ['mixamorigRightHandPinky3', 52, [0, 1.364082, 0.000023], [0, 0, 0, 1]],
+    ['mixamorigRightHandPinky4', 53, [0, 1.668221, 0.000039], [0, 0, 0, 1]],
+    ['mixamorigLeftUpLeg', 0, [9.618273, -5.272293, -1.010886], [1, 0, 0, 0]],
+    ['mixamorigLeftLeg', 55, [0.116409, 43.344528, -1.323286], [0, 0, 0, 1]],
+    ['mixamorigLeftFoot', 56, [-0.102314, 44.292152, 4.219776], [-R2, 0, 0, R2]],
+    ['mixamorigLeftToeBase', 57, [2.599463, 15.813891, 11.814322], [0, 0, 0, 1]],
+    ['mixamorigLeftToe_End', 58, [1.22305, 7.973637, -0.044495], [0, 0, 0, 1]],
+    ['mixamorigRightUpLeg', 0, [-9.940967, -5.27272, -1.211655], [1, 0, 0, 0]],
+    ['mixamorigRightLeg', 60, [-0.103974, 43.304852, -2.031704], [0, 0, 0, 1]],
+    ['mixamorigRightFoot', 61, [0.117103, 44.331413, 4.727186], [-R2, 0, 0, R2]],
+    ['mixamorigRightToeBase', 62, [-2.599469, 15.99981, 11.814546], [0, 0, 0, 1]],
+    ['mixamorigRightToe_End', 63, [-1.223054, 7.92706, -0.044394], [0, 0, 0, 1]],
+];
+/** The hierarchy root bone's canonical name. */
+export const HUMANOID_HIPS_BONE = 'mixamorigHips';
+/** The source rig's armature transform ("Character" node in Soldier.glb):
+ *  Mixamo exports Z-up centimetres; this maps the rig into the scene's
+ *  Y-up metres. Applied to the Group the root bone is parented under. */
+export const ARMATURE_ROTATION_X = -Math.PI / 2;
+export const ARMATURE_SCALE = 0.01;
+/** Build the standard humanoid bone hierarchy from the pure-data table —
+ *  plain `THREE.Bone`s wired parent→child with the source rest pose. */
+export function buildHumanoidSkeleton(defs = MIXAMO_SKELETON_DEF) {
+    const bones = [];
+    const byName = new Map();
+    for (const [name, parentIndex, t, r] of defs) {
+        const bone = new THREE.Bone();
+        bone.name = name;
+        bone.position.set(t[0], t[1], t[2]);
+        bone.quaternion.set(r[0], r[1], r[2], r[3]);
+        bones.push(bone);
+        byName.set(name, bone);
+        // Non-null: the table is topologically ordered (parents precede children).
+        if (parentIndex >= 0)
+            bones[parentIndex].add(bone);
+    }
+    return { root: bones[0], bones, byName };
+}
+/** Wrap a built bone hierarchy in the standard armature group (the Z-up-cm →
+ *  Y-up-m transform every def-table translation is authored against). */
+export function createArmatureGroup(rig) {
+    const armature = new THREE.Group();
+    armature.name = 'Armature';
+    armature.rotation.x = ARMATURE_ROTATION_X;
+    armature.scale.setScalar(ARMATURE_SCALE);
+    armature.add(rig.root);
+    return armature;
+}
+// --- Body-type scaling -----------------------------------------------------
+/** Segment-length groups: each named bone's LOCAL TRANSLATION (= the length of
+ *  the segment ending at that bone) scales by the group's multiplier. Rest
+ *  rotations are never touched — clips own rotations at play time. */
+const TORSO_LENGTH_BONES = new Set([
+    'mixamorigSpine',
+    'mixamorigSpine1',
+    'mixamorigSpine2',
+    'mixamorigNeck',
+    'mixamorigHead',
+]);
+const HEAD_LENGTH_BONES = new Set(['mixamorigHeadTop_End']);
+const ARM_LENGTH_BONES = new Set([
+    'mixamorigLeftForeArm',
+    'mixamorigLeftHand',
+    'mixamorigRightForeArm',
+    'mixamorigRightHand',
+]);
+const LEG_LENGTH_BONES = new Set([
+    'mixamorigLeftLeg',
+    'mixamorigLeftFoot',
+    'mixamorigRightLeg',
+    'mixamorigRightFoot',
+]);
+/** Clavicles (Shoulder→Arm): mostly lateral in the T-pose — whole-vector
+ *  scaled by shoulderWidth. */
+const CLAVICLE_BONES = new Set(['mixamorigLeftArm', 'mixamorigRightArm']);
+/** Shoulder roots off Spine2: X is lateral in the spine frame. */
+const SHOULDER_X_BONES = new Set(['mixamorigLeftShoulder', 'mixamorigRightShoulder']);
+/** Upper-leg roots off Hips: X is lateral in the hips frame. */
+const HIP_X_BONES = new Set(['mixamorigLeftUpLeg', 'mixamorigRightUpLeg']);
+/** Joints whose lowest world-Y point defines the rig's ground clearance. */
+const GROUND_JOINTS = [
+    'mixamorigLeftFoot',
+    'mixamorigRightFoot',
+    'mixamorigLeftToeBase',
+    'mixamorigRightToeBase',
+    'mixamorigLeftToe_End',
+    'mixamorigRightToe_End',
+];
+/** Build the defs under a throwaway armature and read rest-pose world heights. */
+function measureSkeleton(defs) {
+    const rig = buildHumanoidSkeleton(defs);
+    const armature = createArmatureGroup(rig);
+    armature.updateMatrixWorld(true);
+    const p = new THREE.Vector3();
+    let minFootY = Number.POSITIVE_INFINITY;
+    for (const name of GROUND_JOINTS) {
+        const bone = rig.byName.get(name);
+        if (!bone)
+            throw new Error(`humanoid: skeleton def is missing ground joint '${name}'`);
+        p.setFromMatrixPosition(bone.matrixWorld);
+        if (p.y < minFootY)
+            minFootY = p.y;
+    }
+    const headTop = rig.byName.get('mixamorigHeadTop_End');
+    if (!headTop)
+        throw new Error("humanoid: skeleton def is missing 'mixamorigHeadTop_End'");
+    p.setFromMatrixPosition(headTop.matrixWorld);
+    return { minFootY, headTopY: p.y };
+}
+/**
+ * Rescale the reference skeleton table for a body type.
+ *
+ * Order of operations (all in the table's native Z-up cm space):
+ *   1. Per-group segment-length / lateral-width multipliers (never the hips
+ *      row, never any rest rotation).
+ *   2. Re-ground: shift the hips rest translation so the lowest foot joint
+ *      keeps the REFERENCE rig's ground clearance (longer legs raise the
+ *      pelvis, shorter legs lower it — feet never float or sink).
+ *   3. Height normalization: if `params.height` is set, uniformly scale every
+ *      translation so head-top + `crownPadding` lands exactly on it.
+ *
+ * With all-default params every step is an exact no-op (multiplies by 1.0,
+ * adds 0.0), so the default rig is bit-identical to the reference table —
+ * that is what keeps the Phase-1 PoC fixture's committed render valid.
+ *
+ * CLIP COMPATIBILITY (the reviewer-flagged trap): animation clips carry
+ * per-bone `.position` tracks baked for the SOURCE rig's segment lengths.
+ * Played raw on a rescaled skeleton they would snap limbs back to source
+ * proportions. The contract here is split with `clips.ts`: this function
+ * only rescales REST translations and reports `hipsPositionScale`;
+ * `retargetClipToHumanoid` drops every non-hips translation track (bones
+ * keep these rest translations) and remaps the hips track by that factor —
+ * the standard humanoid-retarget policy.
+ */
+export function scaleSkeletonDef(params, crownPadding) {
+    const base = MIXAMO_SKELETON_DEF;
+    const groupFactor = (name) => {
+        if (TORSO_LENGTH_BONES.has(name))
+            return params.torsoLength;
+        if (HEAD_LENGTH_BONES.has(name))
+            return params.headSize;
+        if (ARM_LENGTH_BONES.has(name))
+            return params.armLength;
+        if (LEG_LENGTH_BONES.has(name))
+            return params.legLength;
+        if (CLAVICLE_BONES.has(name))
+            return params.shoulderWidth;
+        return 1;
+    };
+    const scaled = base.map(([name, parent, t, r]) => {
+        const k = groupFactor(name);
+        let [x, y, z] = [t[0] * k, t[1] * k, t[2] * k];
+        if (SHOULDER_X_BONES.has(name))
+            x = t[0] * params.shoulderWidth;
+        if (HIP_X_BONES.has(name))
+            x = t[0] * params.hipWidth;
+        return [name, parent, [x, y, z], r];
+    });
+    // 2. Re-ground the hips against the reference clearance.
+    const reference = measureSkeleton(base);
+    const current = measureSkeleton(scaled);
+    const groundDeltaM = reference.minFootY - current.minFootY;
+    const hips = scaled[0];
+    const hipsT = [
+        hips[2][0],
+        hips[2][1],
+        hips[2][2] + groundDeltaM / ARMATURE_SCALE,
+    ];
+    scaled[0] = [hips[0], hips[1], hipsT, hips[3]];
+    // 3. Height normalization.
+    const naturalHeight = current.headTopY + groundDeltaM + crownPadding;
+    const heightFactor = params.height !== undefined ? params.height / naturalHeight : 1;
+    const finalDefs = heightFactor === 1
+        ? scaled
+        : scaled.map(([name, parent, t, r]) => [
+            name,
+            parent,
+            [t[0] * heightFactor, t[1] * heightFactor, t[2] * heightFactor],
+            r,
+        ]);
+    const baseHips = base[0][2];
+    const finalHips = finalDefs[0][2];
+    const hipsPositionScale = Math.hypot(finalHips[0], finalHips[1], finalHips[2]) /
+        Math.hypot(baseHips[0], baseHips[1], baseHips[2]);
+    return {
+        defs: finalDefs,
+        heightFactor,
+        height: naturalHeight * heightFactor,
+        hipsPositionScale,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `@vgai/engine`'s package `"."` entry — what `import '@vgai/engine'`
+ * resolves to.
+ *
+ * This is a SMALL, CURATED barrel, not a re-export-everything convenience
+ * import. The engine's own doctrine (CLAUDE.md: "the engine code in
+ * `packages/engine/src/` is meant to be read and edited directly — it is
+ * not a black-box library") means subpath imports
+ * (`@vgai/engine/<path>`, matching this package's `"./*"` exports entry)
+ * remain the primary way to reach engine internals — reach for a subpath
+ * first. This barrel exists only so the package's bare-name entry point is
+ * HONEST (resolves to something real and useful) instead of dangling; it
+ * covers just the handful of symbols a game/consumer needs to author a
+ * first-party `setup()` and mount it, plus the scene/manifest file
+ * entry points. Keep it small when extending it — prefer a new subpath
+ * export over growing this file into a firehose.
+ *
+ * Groups (import order below is alphabetical-by-specifier, per the repo's
+ * biome `organizeImports` rule, not by group — see this list instead):
+ *   - game setup contract: `GameContext`/`GameCleanup`/`GameSetupFn`, `fromSetup`
+ *   - component model: `GameComponent`, `AdapterSurface`
+ *   - manifest-driven mount: `mountManifestWorlds` + its option/result types
+ *   - scene file entry point: `parseSceneFile`/`parsePrefabFile`
+ *   - game manifest (vgai.game.json) entry point: `loadGameManifest`
+ */
+export type { AdapterSurface } from './adapter/adapter-surface';
+export { fromSetup } from './adapter/vgai-scene-game-adapter';
+export { GameComponent } from './ecs/game-component';
+export type { AdapterRoot, GameManifest, ResolvedAdapter, ResolvedAdapterRoot, ResolvedGameManifest, RootAdapter, } from './manifest';
+export { CAPABILITY_CEILINGS, DEFAULT_SERVER_MODULE, loadGameManifest } from './manifest';
+export type { GameSession } from './runtime/create-runtime';
+export type { MountEntry, MountedManifestSession, MountManifestOptions, } from './runtime/mount-manifest';
+export { mountManifestWorlds } from './runtime/mount-manifest';
+export type { GameCleanup, GameContext, GameSetupFn } from './runtime/types';
+export { parsePrefabFile, parseSceneFile, SceneParseError } from './scene/parse';
+export type { PrefabFile, SceneFile } from './scene/schema';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,YAAY,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC1F,YAAY,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,YAAY,EACV,UAAU,EACV,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACjF,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,30 @@
+/**
+ * `@vgai/engine`'s package `"."` entry — what `import '@vgai/engine'`
+ * resolves to.
+ *
+ * This is a SMALL, CURATED barrel, not a re-export-everything convenience
+ * import. The engine's own doctrine (CLAUDE.md: "the engine code in
+ * `packages/engine/src/` is meant to be read and edited directly — it is
+ * not a black-box library") means subpath imports
+ * (`@vgai/engine/<path>`, matching this package's `"./*"` exports entry)
+ * remain the primary way to reach engine internals — reach for a subpath
+ * first. This barrel exists only so the package's bare-name entry point is
+ * HONEST (resolves to something real and useful) instead of dangling; it
+ * covers just the handful of symbols a game/consumer needs to author a
+ * first-party `setup()` and mount it, plus the scene/manifest file
+ * entry points. Keep it small when extending it — prefer a new subpath
+ * export over growing this file into a firehose.
+ *
+ * Groups (import order below is alphabetical-by-specifier, per the repo's
+ * biome `organizeImports` rule, not by group — see this list instead):
+ *   - game setup contract: `GameContext`/`GameCleanup`/`GameSetupFn`, `fromSetup`
+ *   - component model: `GameComponent`, `AdapterSurface`
+ *   - manifest-driven mount: `mountManifestWorlds` + its option/result types
+ *   - scene file entry point: `parseSceneFile`/`parsePrefabFile`
+ *   - game manifest (vgai.game.json) entry point: `loadGameManifest`
+ */
+export { fromSetup } from './adapter/vgai-scene-game-adapter';
+export { GameComponent } from './ecs/game-component';
+export { CAPABILITY_CEILINGS, DEFAULT_SERVER_MODULE, loadGameManifest } from './manifest';
+export { mountManifestWorlds } from './runtime/mount-manifest';
+export { parsePrefabFile, parseSceneFile, SceneParseError } from './scene/parse';