@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/character/stages/splitSharedLodSkeletons.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitSharedLodSkeletons = splitSharedLodSkeletons;
+const mergeLods_1 = require("./mergeLods");
+function subtree(roots) {
+    const out = [];
+    const seen = new Set();
+    const stack = [...roots];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (seen.has(node))
+            continue;
+        seen.add(node);
+        out.push(node);
+        stack.push(...node.listChildren());
+    }
+    return out;
+}
+function cloneTree(document, root, map) {
+    if (root.listExtensions().length > 0) {
+        throw new Error(`repair: node '${root.getName()}' carries glTF extensions (${root.listExtensions().map((e) => e.extensionName).join(', ')}) — refusing to clone it lossily`);
+    }
+    const copy = document.createNode(root.getName())
+        .setTranslation([...root.getTranslation()])
+        .setRotation([...root.getRotation()])
+        .setScale([...root.getScale()])
+        .setWeights([...root.getWeights()])
+        .setExtras(structuredClone(root.getExtras()));
+    const mesh = root.getMesh();
+    if (mesh)
+        copy.setMesh(mesh);
+    const skin = root.getSkin();
+    if (skin)
+        copy.setSkin(skin); // remapped once every joint copy exists
+    const camera = root.getCamera();
+    if (camera)
+        copy.setCamera(camera);
+    map.set(root, copy);
+    for (const child of root.listChildren())
+        copy.addChild(cloneTree(document, child, map));
+    return copy;
+}
+function splitSharedLodSkeletons(document) {
+    const scenes = document.getRoot().listScenes();
+    const result = { scenes: scenes.length, scenesRepaired: 0, nodesCloned: 0, skinsCreated: 0 };
+    const owner = new Map();
+    for (const scene of scenes) {
+        for (const node of subtree(scene.listChildren()))
+            if (!owner.has(node))
+                owner.set(node, scene);
+    }
+    for (const scene of scenes) {
+        const shared = scene.listChildren().filter((child) => owner.get(child) !== scene);
+        if (shared.length === 0)
+            continue;
+        const map = new Map();
+        for (const root of shared) {
+            const clone = cloneTree(document, root, map);
+            scene.removeChild(root);
+            scene.addChild(clone);
+        }
+        result.nodesCloned += map.size;
+        result.scenesRepaired++;
+        // Every skinned mesh in this scene that is bound to cloned joints gets a skin over the clones.
+        const rebuilt = new Map();
+        for (const node of subtree(scene.listChildren())) {
+            const skin = node.getSkin();
+            if (!skin)
+                continue;
+            const joints = skin.listJoints();
+            const mapped = joints.map((joint) => map.get(joint));
+            if (mapped.every((joint) => joint === undefined))
+                continue; // bound to this scene's own joints already
+            if (mapped.some((joint) => joint === undefined)) {
+                throw new Error(`repair: skin '${skin.getName()}' in scene '${scene.getName()}' mixes shared and scene-owned joints — cannot split it safely`);
+            }
+            let replacement = rebuilt.get(skin);
+            if (!replacement) {
+                replacement = document.createSkin(skin.getName());
+                for (const joint of mapped)
+                    replacement.addJoint(joint);
+                const ibm = skin.getInverseBindMatrices();
+                if (ibm)
+                    replacement.setInverseBindMatrices(ibm); // same bytes, same accessor: identical binding
+                const skeleton = skin.getSkeleton();
+                if (skeleton)
+                    replacement.setSkeleton(map.get(skeleton) ?? skeleton);
+                replacement.setExtras(structuredClone(skin.getExtras()));
+                rebuilt.set(skin, replacement);
+                result.skinsCreated++;
+            }
+            node.setSkin(replacement);
+        }
+    }
+    scenes.forEach((scene, index) => {
+        const skinned = subtree(scene.listChildren()).filter((node) => node.getMesh() && node.getSkin());
+        if (skinned.length === 0) {
+            throw new Error(`repair: LOD scene ${index + 1} ('${scene.getName()}') has no skinned mesh — it cannot be rebuilt from this file; re-extract the item`);
+        }
+    });
+    (0, mergeLods_1.assertSelfContainedLodScenes)(document);
+    return result;
+}
+//# sourceMappingURL=splitSharedLodSkeletons.js.map

package/dist/character/stages/splitSharedLodSkeletons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"splitSharedLodSkeletons.js","sourceRoot":"","sources":["../../../src/character/stages/splitSharedLodSkeletons.ts"],"names":[],"mappings":"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"}

package/dist/character/stages/unifyMaterial.d.ts

@@ -0,0 +1,66 @@
+import type { Document } from '@gltf-transform/core';
+/**
+ * COLLAPSING A GARMENT'S CROSS-LOD MATERIAL DUPLICATION DOWN TO A LOW ADDON CAP.
+ *
+ * `importCharacter`'s LOD loop bakes or re-resizes each LOD level's textures independently (a
+ * genuine quality choice — LOD2 gets a smaller texture than LOD0, not a shared one), so the SAME
+ * named material can carry genuinely different texture bytes per LOD. `mergeLods` combines every
+ * level's scene into one document but does not (and should not) fold those apart-by-design variants
+ * back together: gltf-transform's own `dedup()` correctly leaves them alone, since the textures
+ * really do differ. For most add-on slots that is fine — 2-3 materials per LOD level is well under
+ * budget. It stops being fine for a slot with a LOW material cap (mask/footwear's real-world 2-4
+ * material ceiling): 2 unique per-LOD materials across 3 LODs is 6 material slots, well over.
+ *
+ * A real per-material texture atlas (baking every LOD's variant of one named material into a single
+ * texture) is the quality-preserving fix and is future work. This is the pragmatic one already
+ * proven out by hand across the male wearables pilot: rebind every primitive in the document onto
+ * whichever material covers the MOST triangles — not the biggest texture, which a small decorative
+ * accent (e.g. stitching detail) can carry more of than the garment's own main body — and prune the
+ * rest. A lower LOD loses its own downsized texture and reuses the higher-detail one instead, which
+ * costs nothing in quality (strictly better) and only a little more texture memory (already-loaded,
+ * shared, not duplicated).
+ */
+export interface UnifyMaterialOptions {
+    /** Hard ceiling on materials in the output. Only acts when the document is already over it. */
+    readonly maxMaterials: number;
+    /**
+     * Whether every LOD scene samples the SAME texture coordinates. True (default) on the plain route, where
+     * each LOD is a simplification of one UV layout, so rebinding a lower LOD onto LOD0's material is lossless.
+     * FALSE on the rebake route: each level is re-unwrapped and re-baked into its OWN atlas, so a lower LOD's
+     * UVs index into a different image than LOD0's. Rebinding it onto LOD0's material makes it sample garbage
+     * (measured on a live cargo-pants add-on: 28% of LOD1/LOD2 triangles landed on pure-black background
+     * texels of LOD0's atlas). With this false, every scene is unified onto its OWN dominant material, so the
+     * result is at most one material per LOD; only if even that is over the cap does it fall back to the
+     * cross-LOD rebinding (and says so in `crossSceneFallback`).
+     */
+    readonly shareAcrossScenes?: boolean;
+}
+export interface UnifyMaterialResult {
+    materialsBefore: number;
+    materialsAfter: number;
+    /** Name of the material every primitive was rebound onto, or null when already within budget (no-op). */
+    dominant: string | null;
+    /** Primitives whose material assignment actually changed. */
+    rebound: number;
+    /**
+     * Alpha-MASK materials folded into an OPAQUE dominant by promoting the dominant to MASK (their cutout survives).
+     * Only done when both bind the same base-colour texture, which is how the rebake route builds a shared atlas
+     * whose alpha channel already carries the cutout and is 255 on every opaque chart.
+     */
+    cutoutsPromoted: number;
+    /** Primitives of a MASK/BLEND material rebound onto a material that could not keep their cutout: they now draw solid. */
+    cutoutsFlattened: number;
+    /** `shareAcrossScenes: false` was requested but per-scene unification still exceeded the cap, so LOD scenes were rebound across scenes. */
+    crossSceneFallback: boolean;
+}
+/**
+ * Rebinds primitives onto a dominant-by-triangle-count material when the document carries more materials
+ * than `options.maxMaterials`, then prunes the now-unused materials/textures. A no-op (untouched document)
+ * when already within budget — the same "don't pay for what you don't need" convention `atlasMaterials`
+ * uses for its own cap.
+ *
+ * By default ONE dominant material serves the whole document. With `shareAcrossScenes: false` (the rebake
+ * route, where each LOD scene has its own atlas and UV layout) each LOD scene is unified onto its own dominant
+ * instead; see the option's note.
+ */
+export declare function unifyDominantMaterial(document: Document, options: UnifyMaterialOptions): Promise<UnifyMaterialResult>;

package/dist/character/stages/unifyMaterial.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unifyDominantMaterial = unifyDominantMaterial;
+const functions_1 = require("@gltf-transform/functions");
+/** Triangles a primitive covers — the "how much of the garment does this material actually draw" measure. */
+function triangleCountOf(primitive) {
+    const indices = primitive.getIndices();
+    if (indices !== null)
+        return Math.floor(indices.getCount() / 3);
+    const position = primitive.getAttribute('POSITION');
+    return position !== null ? Math.floor(position.getCount() / 3) : 0;
+}
+/** Every primitive of every mesh reachable from `scene`, once. */
+function scenePrimitives(scene, seen) {
+    const out = [];
+    scene.traverse((node) => {
+        const mesh = node.getMesh();
+        if (mesh === null)
+            return;
+        for (const primitive of mesh.listPrimitives()) {
+            if (seen.has(primitive))
+                continue;
+            seen.add(primitive);
+            out.push(primitive);
+        }
+    });
+    return out;
+}
+/** The material bound to the most triangles among `primitives`; null when none is textured/bound. */
+function dominantOf(primitives) {
+    const tris = new Map();
+    for (const primitive of primitives) {
+        const material = primitive.getMaterial();
+        if (material === null)
+            continue;
+        tris.set(material, (tris.get(material) ?? 0) + triangleCountOf(primitive));
+    }
+    let dominant = null;
+    let best = -1;
+    for (const [material, count] of tris) {
+        if (count > best) {
+            dominant = material;
+            best = count;
+        }
+    }
+    return dominant;
+}
+/**
+ * Rebinds one primitive onto `dominant` WITHOUT silently discarding a cutout.
+ *
+ * A decorative overlay is often an alpha-MASK material (stitching, lace, mesh panels). Rebinding it onto an
+ * OPAQUE material used to draw its transparent texels solid — on a live pair of garments that read as grey,
+ * glossy outlines along every panel edge. When both materials bind the SAME base-colour texture (the rebake
+ * route's shared atlas: the cutout is already in its alpha channel, and every opaque chart is alpha 255) the
+ * dominant is promoted to MASK instead, so the overlay keeps its holes and the rest draws exactly as before.
+ * Otherwise (different textures, or BLEND) nothing honest can be done here, so it is counted for the caller to report.
+ */
+function rebind(primitive, dominant, result) {
+    const from = primitive.getMaterial();
+    if (from === dominant)
+        return;
+    if (from !== null && from.getAlphaMode() !== 'OPAQUE' && dominant.getAlphaMode() === 'OPAQUE') {
+        const sharedAtlas = from.getBaseColorTexture() !== null && from.getBaseColorTexture() === dominant.getBaseColorTexture();
+        if (from.getAlphaMode() === 'MASK' && sharedAtlas) {
+            const [r, g, b] = dominant.getBaseColorFactor();
+            // An OPAQUE material's factor alpha is ignored by renderers and is routinely 0 in extracted sources; under MASK it would clip everything.
+            dominant.setAlphaMode('MASK').setAlphaCutoff(from.getAlphaCutoff()).setBaseColorFactor([r, g, b, 1]);
+            result.cutoutsPromoted++;
+        }
+        else {
+            result.cutoutsFlattened++;
+        }
+    }
+    else if (from !== null && from.getAlphaMode() === 'MASK' && dominant.getAlphaMode() === 'MASK' && from.getBaseColorTexture() !== null && from.getBaseColorTexture() === dominant.getBaseColorTexture()) {
+        result.cutoutsPromoted++; // already MASK on the shared atlas: the overlay keeps its holes
+    }
+    primitive.setMaterial(dominant);
+    result.rebound++;
+}
+/**
+ * Rebinds primitives onto a dominant-by-triangle-count material when the document carries more materials
+ * than `options.maxMaterials`, then prunes the now-unused materials/textures. A no-op (untouched document)
+ * when already within budget — the same "don't pay for what you don't need" convention `atlasMaterials`
+ * uses for its own cap.
+ *
+ * By default ONE dominant material serves the whole document. With `shareAcrossScenes: false` (the rebake
+ * route, where each LOD scene has its own atlas and UV layout) each LOD scene is unified onto its own dominant
+ * instead; see the option's note.
+ */
+async function unifyDominantMaterial(document, options) {
+    const root = document.getRoot();
+    const before = root.listMaterials().length;
+    const result = { materialsBefore: before, materialsAfter: before, dominant: null, rebound: 0, cutoutsPromoted: 0, cutoutsFlattened: 0, crossSceneFallback: false };
+    if (before <= options.maxMaterials)
+        return result;
+    const every = [];
+    for (const mesh of root.listMeshes())
+        every.push(...mesh.listPrimitives());
+    const globalDominant = dominantOf(every);
+    if (globalDominant === null)
+        return result; // nothing textured to unify onto
+    // Plan the per-scene unification BEFORE touching anything, so an over-cap outcome can fall back cleanly.
+    let groups = null;
+    const scenes = root.listScenes();
+    if (options.shareAcrossScenes === false && scenes.length > 1) {
+        const seen = new Set();
+        const planned = [];
+        for (const scene of scenes) {
+            const primitives = scenePrimitives(scene, seen);
+            const dominant = dominantOf(primitives);
+            if (dominant !== null)
+                planned.push({ primitives, dominant });
+        }
+        const leftovers = every.filter((primitive) => !seen.has(primitive));
+        if (leftovers.length === 0 && new Set(planned.map((group) => group.dominant)).size <= options.maxMaterials)
+            groups = planned;
+        else
+            result.crossSceneFallback = true;
+    }
+    if (groups !== null) {
+        for (const group of groups) {
+            for (const primitive of group.primitives)
+                rebind(primitive, group.dominant, result);
+        }
+        result.dominant = groups.map((group) => group.dominant.getName()).join(', ');
+    }
+    else {
+        for (const primitive of every)
+            rebind(primitive, globalDominant, result);
+        result.dominant = globalDominant.getName();
+    }
+    await document.transform((0, functions_1.prune)());
+    result.materialsAfter = root.listMaterials().length;
+    return result;
+}
+//# sourceMappingURL=unifyMaterial.js.map

package/dist/character/stages/unifyMaterial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unifyMaterial.js","sourceRoot":"","sources":["../../../src/character/stages/unifyMaterial.ts"],"names":[],"mappings":"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"}

package/dist/character/stages/vrmDynamics.d.ts

@@ -0,0 +1,144 @@
+/**
+ * VRM SpringBone → `helix/dynamics@1`.
+ *
+ * ── WHY VRM FIRST ──────────────────────────────────────────────────────────────────────────────────────────────
+ * It is the only openly specified secondary-motion format with a large body of real content, the configuration
+ * travels INSIDE the .vrm (unlike a Unity prefab, where the parameters live in a scene file that never ships),
+ * and both major versions are readable without a game engine. That makes it the honest first target for an
+ * importer and the honest test corpus for a solver. VRChat PhysBone conversion is the same shape of problem with
+ * a harder extraction step, and lands on this same intermediate form.
+ *
+ * ── THE HARD PART IS UNITS, NOT STRUCTURE ──────────────────────────────────────────────────────────────────────
+ * Chains and colliders map across almost mechanically. The parameters do not, and this is where every naive
+ * converter goes wrong — including, by its own admission, VRChat's:
+ *
+ *   · VRM `stiffness` is **world units per second**. It is added to the tail as `axis * stiffness * dt`, then the
+ *     tail is projected back to its authored bone length. The projection couples stiffness, bone length and drag;
+ *     none of the three can be converted independently without changing the response.
+ *
+ *   · VRM `dragForce` is a per-FRAME velocity multiplier. Three-vrm's reference Verlet step retains
+ *     `(1 - dragForce)` of the previous displacement once per update while stiffness and gravity are scaled by
+ *     dt. Converting it means choosing the frame rate it was authored against; 60 Hz is the preview convention.
+ *     We linearise that exact projected step and map its two discrete poles to the continuous spring's poles.
+ *     This preserves both oscillation frequency and decay instead of equating velocity retention alone, which
+ *     over-damped ordinary VRoid hair and flattened distinct authored values at the critical-damping clamp.
+ *
+ *   · VRM `gravityPower` is likewise a velocity, not an acceleration, so it cannot be read as m/s². The
+ *     conversion goes through the EQUILIBRIUM instead: in VRM the rest droop satisfies
+ *     `tan θ ≈ gravityPower / stiffness`, and in this solver the sag is `g / (ω²L)`. Setting those equal gives
+ *     `g = gravityPower * ω²L / stiffness`, using the bounded ω this converter actually emits. That preserves
+ *     how far a chain hangs rather than preserving a number that means something different on each side.
+ *
+ * None of this is exact, and it is not claimed to be. The research that produced these relations fitted them
+ * numerically and found parameter recovery good but multi-joint waveforms drifting in phase over seconds. The
+ * goal is a chain that hangs and swings the way the author intended, not one that matches frame for frame.
+ */
+export declare const VRM_ASSUMED_AUTHORING_HZ = 60;
+/**
+ * Inertia given to a chain whose VRM declares a `center` node.
+ *
+ * VRoid writes a `center` BY DEFAULT — its UI calls the option "prevent excessive sway during movement" — so a
+ * large share of real VRM files depend on it, and a converter that ignores it produces hair that flails while
+ * the character merely walks. Measured across the reference set: `AvatarSample_B` centres all 11 of its groups
+ * and `Seed-san` 8 of its 9 springs, while `Vivi` and `AliciaSolid` centre nothing at all.
+ *
+ * True centre-space integration resolves motion against the named node — usually the hips — and is a V2 item;
+ * it needs the character root transform, which a chain anchored to the head does not have. This is the honest
+ * approximation available to a per-anchor scalar: carry most of the anchor's motion, keep some lag. It is
+ * deliberately not 1.0, because full carry would also cancel the head-turn response that makes hair read as
+ * hair, and the failure it is fixing is gross body translation, not rotation.
+ */
+export declare const CENTRE_INERTIA = 0.6;
+export interface ImportedChain {
+    id: string;
+    root: string;
+    importance: 'critical' | 'high' | 'normal' | 'decorative';
+    stiffness: number;
+    damping: number;
+    inertia?: number;
+    gravity?: number;
+    gravityDir?: [number, number, number];
+    radius?: number;
+    colliders?: string[];
+    endpoint?: [number, number, number];
+}
+export interface ImportedCollider {
+    id: string;
+    bone: string;
+    shape: 'sphere' | 'capsule';
+    offset?: [number, number, number];
+    radius: number;
+    tail?: [number, number, number];
+    inside?: boolean;
+}
+export interface VrmImportResult {
+    contract: 'helix/dynamics@1';
+    chains: ImportedChain[];
+    colliders: ImportedCollider[];
+    /** Anything dropped or approximated, in creator-readable terms. */
+    warnings: string[];
+    /** `0.x` or `1.0`, for reporting. */
+    sourceVersion: string;
+}
+/** ω (rad/s) → the contract's normalised 0..1 stiffness. The inverse of `stiffnessToOmega`. */
+export declare function omegaToStiffness(omega: number): number;
+/** Continuous response plus its bounded `helix/dynamics@1` representation. */
+export interface ConvertedSpring {
+    /** Unclamped continuous natural frequency, in rad/s. */
+    omega: number;
+    /** Unclamped continuous damping ratio. Values above one cannot be represented by dynamics@1. */
+    dampingRatio: number;
+    /** Natural frequency of the closest representable response, before the engine's 2..40 rad/s clamp. */
+    mappedOmega: number;
+    /** Natural frequency after the dynamics@1 clamp; this is what the runtime actually solves. */
+    engineOmega: number;
+    /** Damping ratio of the bounded dynamics@1 representation. */
+    mappedDampingRatio: number;
+    /** Normalised dynamics@1 stiffness. */
+    stiffness: number;
+    /** Normalised dynamics@1 damping. */
+    damping: number;
+}
+/**
+ * Convert one VRM projected-Verlet joint to the continuous `helix/dynamics@1` spring.
+ *
+ * For a small angular displacement `x`, three-vrm's documented update linearises to:
+ *
+ *     q = 1 + (stiffness / boneLength) dt
+ *     x[n+1] = ((1 + retention) / q) x[n] - (retention / q) x[n-1]
+ *
+ * The roots of that recurrence are the response sampled at the authoring rate. Mapping their magnitude and
+ * phase to `exp((-ζω ± iωd)dt)` gives the continuous spring parameters directly. Dynamics@1 cannot express an
+ * overdamped response, so real positive roots map to a critical spring at the slow pole's rate. That preserves
+ * the visible return tail by lowering stiffness, as the contract requires, instead of clamping damping while
+ * retaining the geometric-mean frequency and making a heavily dragged chain snap back too quickly.
+ */
+export declare function convertSpring(vrmStiffness: number, dragForce: number, boneLengthM: number, hz?: number): ConvertedSpring;
+/** VRM `gravityPower` → a multiplier on real world gravity, via the equilibrium droop. See the header. */
+export declare function convertGravity(gravityPower: number, vrmStiffness: number, boneLengthM: number, engineOmega: number): number;
+/**
+ * Guess how much a chain matters from its bone names.
+ *
+ * Importance drives the frame budget, so getting it roughly right is what lets a crowd degrade sensibly rather
+ * than uniformly. Nothing in VRM carries this, and asking a creator to hand-classify twenty-two chains is the
+ * kind of chore the platform is supposed to absorb. Names in real content are remarkably consistent — VRoid
+ * emits `J_Sec_Hair*`, `*Skirt*`, `*Bust*` — so a table gets most of it, and it is only ever a default.
+ */
+export declare function guessImportance(name: string): ImportedChain['importance'];
+interface GltfNode {
+    name?: string;
+    children?: number[];
+    translation?: number[];
+}
+interface GltfLike {
+    nodes?: GltfNode[];
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Convert the spring-bone configuration of a parsed VRM glTF document.
+ *
+ * Takes the JSON chunk, not a file path or a three.js scene, so it runs in the pipeline, in a test, and in a
+ * browser importer without change.
+ */
+export declare function convertVrmDynamics(gltf: GltfLike): VrmImportResult | null;
+export {};