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

package/dist/character/stages/faceRegion.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.faceTriangleMask = faceTriangleMask;
+exports.splitFaceForUnwrap = splitFaceForUnwrap;
+exports.rejoinFaceSplits = rejoinFaceSplits;
+exports.faceChartScale = faceChartScale;
+const functions_1 = require("@gltf-transform/functions");
+const mat4_1 = require("../mat4");
+const DEFAULT_MIN_HEAD_WEIGHT = 0.5;
+const DEFAULT_MIN_FACING = 0.25;
+const DEFAULT_CHIN_DROP = 0.15;
+/** The skinned node that draws `prim`, or null (an unskinned primitive has no head to protect). */
+function skinnedHostOf(document, prim) {
+    for (const node of document.getRoot().listNodes()) {
+        const mesh = node.getMesh();
+        if (mesh !== null && node.getSkin() !== null && mesh.listPrimitives().includes(prim))
+            return node;
+    }
+    return null;
+}
+/** Joint indices of the head subtree in `node`'s skin ('head' and descendants; neck subtree as fallback), plus the
+ * subtree root's bind-pose position in mesh space (inverse of its inverse-bind matrix). */
+function headJoints(node) {
+    const skin = node.getSkin();
+    const joints = skin.listJoints();
+    const root = joints.find((j) => j.getName() === 'head') ?? joints.find((j) => j.getName() === 'neck_02') ?? joints.find((j) => j.getName() === 'neck_01');
+    if (root === undefined)
+        return null;
+    const set = new Set();
+    const mark = (n) => {
+        const i = joints.indexOf(n);
+        if (i >= 0)
+            set.add(i);
+        for (const child of n.listChildren())
+            mark(child);
+    };
+    mark(root);
+    const ibm = skin.getInverseBindMatrices();
+    let origin;
+    if (ibm !== null) {
+        const m = Array.from(ibm.getElement(joints.indexOf(root), []));
+        const bind = (0, mat4_1.invert4)(m);
+        origin = [bind[12], bind[13], bind[14]];
+    }
+    else {
+        const [x, y, z] = root.getWorldTranslation();
+        origin = [x, y, z];
+    }
+    return { set, origin };
+}
+/**
+ * Per-TRIANGLE face mask over `prim`'s current index buffer (1 = face), or null when the primitive is not a skinned
+ * indexed triangle list or its rig has no head joint. Pure read; never mutates the document.
+ */
+function faceTriangleMask(document, prim, options = {}) {
+    const indices = prim.getIndices();
+    const position = prim.getAttribute('POSITION');
+    const j0 = prim.getAttribute('JOINTS_0');
+    const w0 = prim.getAttribute('WEIGHTS_0');
+    if (prim.getMode() !== 4 || indices === null || position === null || j0 === null || w0 === null)
+        return null;
+    const host = skinnedHostOf(document, prim);
+    if (host === null)
+        return null;
+    const joints = headJoints(host);
+    if (joints === null)
+        return null;
+    const head = joints.set;
+    const minHead = options.minHeadWeight ?? DEFAULT_MIN_HEAD_WEIGHT;
+    const minFacing = options.minFacing ?? DEFAULT_MIN_FACING;
+    const [fx, fy, fz] = options.forward ?? [0, 0, 1];
+    const chinDrop = options.chinDrop ?? DEFAULT_CHIN_DROP;
+    const headness = new Float32Array(j0.getCount());
+    const jv = [], wv = [];
+    for (let v = 0; v < headness.length; v++) {
+        j0.getElement(v, jv);
+        w0.getElement(v, wv); // getElement denormalizes quantized weights
+        let h = 0;
+        for (let c = 0; c < 4; c++)
+            if (head.has(jv[c]))
+                h += wv[c];
+        headness[v] = h;
+    }
+    const pos = position.getArray();
+    const idx = indices.getArray();
+    // Up = +Y in the conformed frame. Chin line: the head joint minus `chinDrop` of the head's height above it.
+    let top = joints.origin[1];
+    for (let v = 0; v < headness.length; v++)
+        if (headness[v] > minHead && pos[v * 3 + 1] > top)
+            top = pos[v * 3 + 1];
+    const chinY = joints.origin[1] - chinDrop * (top - joints.origin[1]);
+    const mask = new Uint8Array(idx.length / 3);
+    for (let t = 0; t < mask.length; t++) {
+        const a = idx[t * 3], b = idx[t * 3 + 1], c = idx[t * 3 + 2];
+        if ((headness[a] + headness[b] + headness[c]) / 3 <= minHead)
+            continue;
+        if ((pos[a * 3 + 1] + pos[b * 3 + 1] + pos[c * 3 + 1]) / 3 < chinY)
+            continue;
+        const ux = pos[b * 3] - pos[a * 3], uy = pos[b * 3 + 1] - pos[a * 3 + 1], uz = pos[b * 3 + 2] - pos[a * 3 + 2];
+        const vx = pos[c * 3] - pos[a * 3], vy = pos[c * 3 + 1] - pos[a * 3 + 1], vz = pos[c * 3 + 2] - pos[a * 3 + 2];
+        const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx;
+        const len = Math.hypot(nx, ny, nz);
+        if (len === 0)
+            continue;
+        if ((nx * fx + ny * fy + nz * fz) / len > minFacing)
+            mask[t] = 1;
+    }
+    return mask;
+}
+/**
+ * Moves each skinned primitive's face triangles into a sibling primitive (same mesh, same material, SHARED attribute
+ * accessors — only the index buffer splits), so an unwrap can scale the face's charts independently: xatlas never
+ * builds a chart across primitives. `rejoinFaceSplits` folds them back after the bake. Returns one entry per split.
+ */
+function splitFaceForUnwrap(document, options = {}) {
+    const buffer = document.getRoot().listBuffers()[0];
+    const splits = [];
+    for (const mesh of document.getRoot().listMeshes()) {
+        for (const prim of mesh.listPrimitives()) {
+            const mask = faceTriangleMask(document, prim, options);
+            if (mask === null)
+                continue;
+            const idx = prim.getIndices().getArray();
+            const pos = prim.getAttribute('POSITION').getArray();
+            const face = [], body = [];
+            let faceArea = 0, totalArea = 0;
+            for (let t = 0; t < mask.length; t++) {
+                const a = idx[t * 3], b = idx[t * 3 + 1], c = idx[t * 3 + 2];
+                const area = triangleArea(pos, a, b, c);
+                totalArea += area;
+                if (mask[t] === 1) {
+                    face.push(a, b, c);
+                    faceArea += area;
+                }
+                else
+                    body.push(a, b, c);
+            }
+            if (face.length === 0 || body.length === 0)
+                continue;
+            prim.setIndices(document.createAccessor().setType('SCALAR').setArray(new Uint32Array(body)).setBuffer(buffer));
+            const facePrim = document.createPrimitive().setMode(4).setMaterial(prim.getMaterial())
+                .setIndices(document.createAccessor().setType('SCALAR').setArray(new Uint32Array(face)).setBuffer(buffer));
+            for (const semantic of prim.listSemantics())
+                facePrim.setAttribute(semantic, prim.getAttribute(semantic));
+            mesh.addPrimitive(facePrim);
+            splits.push({ body: prim, face: facePrim, faceAreaShare: totalArea > 0 ? faceArea / totalArea : 0 });
+        }
+    }
+    return splits;
+}
+/** Folds each face primitive back into its body primitive (one draw call again), in place in the same mesh. */
+function rejoinFaceSplits(document, splits) {
+    for (const { body, face } of splits) {
+        const mesh = document.getRoot().listMeshes().find((m) => m.listPrimitives().includes(body));
+        if (mesh === undefined)
+            continue;
+        const joined = (0, functions_1.joinPrimitives)([body, face]);
+        mesh.removePrimitive(face);
+        mesh.removePrimitive(body);
+        mesh.addPrimitive(joined);
+        for (const prim of [face, body])
+            if (prim.listParents().every((p) => p === document.getRoot()))
+                prim.dispose();
+    }
+}
+/**
+ * Linear scale for the face's charts in the unwrap so the face gets `boost` x the body's texel density, reduced
+ * so the face never takes more than `maxShare` of the packed atlas area. With face area fraction f and linear scale
+ * s, the face's atlas share is f s^2 / (f s^2 + 1 - f).
+ */
+function faceChartScale(faceAreaShare, boost, maxShare) {
+    const f = faceAreaShare;
+    if (!(f > 0) || f >= 1 || boost <= 1)
+        return 1;
+    const capped = Math.sqrt((maxShare * (1 - f)) / (f * (1 - maxShare)));
+    return Math.max(1, Math.min(boost, capped));
+}
+function triangleArea(pos, a, b, c) {
+    const ux = pos[b * 3] - pos[a * 3], uy = pos[b * 3 + 1] - pos[a * 3 + 1], uz = pos[b * 3 + 2] - pos[a * 3 + 2];
+    const vx = pos[c * 3] - pos[a * 3], vy = pos[c * 3 + 1] - pos[a * 3 + 1], vz = pos[c * 3 + 2] - pos[a * 3 + 2];
+    return Math.hypot(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx) / 2;
+}
+//# sourceMappingURL=faceRegion.js.map

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

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

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

@@ -0,0 +1,42 @@
+import type { Document } from '@gltf-transform/core';
+/**
+ * WHICH SURFACES THE CAMERA IS INSIDE, DECLARED BY THE AVATAR.
+ *
+ * In first person the camera rides the head bone, so anything skinned to the head is around the lens: the face
+ * fills the view, hair cards cut through the near plane, ears clip in from the sides. The engine already
+ * handles this — `CameraRig` ref-counts a hide request per mesh-name matcher, pops it for the look-down
+ * embodiment and pops it again for the selfie camera so your own face is in your own photo.
+ *
+ * What it could not handle was an avatar that is not Base Male. The matcher list defaulted to `['FaceMesh']`,
+ * which is the name of one mesh in one first-party pack. An imported VRoid avatar's head mesh is called
+ * `Face (merged).baked`; the substring never matched, nothing was ever hidden, and every imported character
+ * put its own face through the camera in first person. A convention that only one asset satisfies is not a
+ * contract — so the avatar now DECLARES its head surfaces and the runtime reads them.
+ *
+ * Selection is by skin weight, not by name. A mesh is head-attached when the overwhelming majority of its
+ * weight sits on the head joint or something descended from it, which is true of a face, a hair card and a cat
+ * ear, and false of a torso that happens to have a collar near the neck. Names are unreliable across exporters
+ * in exactly the way this whole problem demonstrates.
+ */
+/**
+ * The vertices a primitive actually draws.
+ *
+ * VRoid shares one JOINTS_0/WEIGHTS_0 accessor across every primitive in a mesh, so reading the whole
+ * attribute answers a question about the MESH, not about this surface — and every primitive in `Body
+ * (merged).baked` then gets the same verdict, which put the cat ears in the same bucket as the shoes. Only the
+ * indexed vertices belong to this primitive.
+ */
+export declare function primitiveVertices(primitive: import('@gltf-transform/core').Primitive): Set<number>;
+export interface FirstPersonHideResult {
+    /** Runtime mesh names to hide, in the form `GLTFLoader` will produce them. */
+    readonly meshes: string[];
+    /** Primitives examined, for the report. */
+    readonly examined: number;
+}
+/**
+ * Find every primitive the first-person camera sits inside, and write the list into each scene's extras.
+ *
+ * Returns the names rather than only stamping them so the caller can report what it hid — an avatar that
+ * declares nothing is a first-person bug waiting to be filed, and it should be visible at import time.
+ */
+export declare function declareFirstPersonHide(document: Document): FirstPersonHideResult;

package/dist/character/stages/firstPersonHide.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.primitiveVertices = primitiveVertices;
+exports.declareFirstPersonHide = declareFirstPersonHide;
+/**
+ * WHICH SURFACES THE CAMERA IS INSIDE, DECLARED BY THE AVATAR.
+ *
+ * In first person the camera rides the head bone, so anything skinned to the head is around the lens: the face
+ * fills the view, hair cards cut through the near plane, ears clip in from the sides. The engine already
+ * handles this — `CameraRig` ref-counts a hide request per mesh-name matcher, pops it for the look-down
+ * embodiment and pops it again for the selfie camera so your own face is in your own photo.
+ *
+ * What it could not handle was an avatar that is not Base Male. The matcher list defaulted to `['FaceMesh']`,
+ * which is the name of one mesh in one first-party pack. An imported VRoid avatar's head mesh is called
+ * `Face (merged).baked`; the substring never matched, nothing was ever hidden, and every imported character
+ * put its own face through the camera in first person. A convention that only one asset satisfies is not a
+ * contract — so the avatar now DECLARES its head surfaces and the runtime reads them.
+ *
+ * Selection is by skin weight, not by name. A mesh is head-attached when the overwhelming majority of its
+ * weight sits on the head joint or something descended from it, which is true of a face, a hair card and a cat
+ * ear, and false of a torso that happens to have a collar near the neck. Names are unreliable across exporters
+ * in exactly the way this whole problem demonstrates.
+ */
+/**
+ * The vertices a primitive actually draws.
+ *
+ * VRoid shares one JOINTS_0/WEIGHTS_0 accessor across every primitive in a mesh, so reading the whole
+ * attribute answers a question about the MESH, not about this surface — and every primitive in `Body
+ * (merged).baked` then gets the same verdict, which put the cat ears in the same bucket as the shoes. Only the
+ * indexed vertices belong to this primitive.
+ */
+function primitiveVertices(primitive) {
+    const vertices = new Set();
+    const indices = primitive.getIndices();
+    if (indices !== null) {
+        for (let i = 0; i < indices.getCount(); i++)
+            vertices.add(indices.getScalar(i));
+        return vertices;
+    }
+    const position = primitive.getAttribute('POSITION');
+    for (let i = 0; i < (position?.getCount() ?? 0); i++)
+        vertices.add(i);
+    return vertices;
+}
+/** Above this share of head-descended weight, the camera is inside the surface. */
+const HEAD_WEIGHT_SHARE = 0.8;
+/** The joint every head surface hangs from, in `helix-humanoid@1`. */
+const HEAD_JOINT = 'head';
+/**
+ * Runtime names for a mesh's primitives.
+ *
+ * `GLTFLoader` splits a multi-primitive mesh into one `Mesh` per primitive, naming the first after the mesh and
+ * suffixing the rest `_1`, `_2`… Matching is by substring, so the base name alone would hide every primitive in
+ * the mesh — which is wrong for a body mesh that carries the ears as one primitive among many.
+ */
+function runtimeName(meshName, primitiveIndex) {
+    // three.js `PropertyBinding.sanitizeNodeName`, reproduced exactly: whitespace becomes `_` and the characters
+    // reserved by its track-name grammar (`[`, `]`, `.`, `:`, `/`) are dropped. Everything else survives —
+    // parentheses included. Guessing at this instead of matching it produced `Facemergedbaked` for a mesh the
+    // runtime calls `Face_(merged)baked`, which matches nothing and hides nothing.
+    const sanitized = meshName.replace(/\s/g, '_').replace(/[[\].:/]/g, '');
+    return primitiveIndex === 0 ? sanitized : `${sanitized}_${primitiveIndex}`;
+}
+/**
+ * Find every primitive the first-person camera sits inside, and write the list into each scene's extras.
+ *
+ * Returns the names rather than only stamping them so the caller can report what it hid — an avatar that
+ * declares nothing is a first-person bug waiting to be filed, and it should be visible at import time.
+ */
+function declareFirstPersonHide(document) {
+    const root = document.getRoot();
+    const meshes = [];
+    let examined = 0;
+    for (const skin of root.listSkins()) {
+        const joints = skin.listJoints();
+        const headIndex = joints.findIndex((joint) => joint.getName() === HEAD_JOINT);
+        if (headIndex < 0)
+            continue;
+        // Everything descended from the head, by walking the joint list's own parent chain.
+        const head = joints[headIndex];
+        const headDescendants = new Set();
+        joints.forEach((joint, index) => {
+            let cursor = joint;
+            while (cursor !== null) {
+                if (cursor === head) {
+                    headDescendants.add(index);
+                    return;
+                }
+                cursor = cursor.getParentNode();
+            }
+        });
+        if (headDescendants.size === 0)
+            continue;
+        for (const node of root.listNodes()) {
+            if (node.getSkin() !== skin)
+                continue;
+            const mesh = node.getMesh();
+            if (mesh === null)
+                continue;
+            mesh.listPrimitives().forEach((primitive, primitiveIndex) => {
+                examined++;
+                const joints0 = primitive.getAttribute('JOINTS_0');
+                const weights0 = primitive.getAttribute('WEIGHTS_0');
+                if (joints0 === null || weights0 === null)
+                    return;
+                let headWeight = 0;
+                let total = 0;
+                // `getElement`, not `getArray`: the element accessor is the one that stays correct whatever the
+                // underlying layout is. Reading raw arrays out of skin attributes has already cost this pipeline two
+                // rounds of wrong diagnoses.
+                const jointSlot = [0, 0, 0, 0];
+                const weightSlot = [0, 0, 0, 0];
+                for (const vertex of primitiveVertices(primitive)) {
+                    joints0.getElement(vertex, jointSlot);
+                    weights0.getElement(vertex, weightSlot);
+                    for (let slot = 0; slot < 4; slot++) {
+                        const weight = weightSlot[slot];
+                        if (weight <= 0)
+                            continue;
+                        total += weight;
+                        if (headDescendants.has(jointSlot[slot]))
+                            headWeight += weight;
+                    }
+                }
+                if (total > 0 && headWeight / total >= HEAD_WEIGHT_SHARE) {
+                    meshes.push(runtimeName(mesh.getName(), primitiveIndex));
+                }
+            });
+        }
+    }
+    if (meshes.length > 0) {
+        for (const scene of root.listScenes()) {
+            const extras = scene.getExtras();
+            const avatar = extras.helixAvatar ?? {};
+            scene.setExtras({ ...extras, helixAvatar: { ...avatar, firstPersonHide: meshes } });
+        }
+    }
+    return { meshes, examined };
+}
+//# sourceMappingURL=firstPersonHide.js.map

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

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

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

@@ -0,0 +1,18 @@
+import type { Document } from '@gltf-transform/core';
+/**
+ * Joins same-material, same-mode primitives WITHIN each mesh (i.e. within one LOD level's own
+ * scene), never ACROSS meshes/LODs — a merged-LOD document keeps every level's own mesh, and
+ * primitives from different levels must never end up sharing one draw call. Most useful right after
+ * `unifyDominantMaterial`: once every primitive in a mesh is rebound onto the same material, the
+ * primitives that were only ever kept separate because they carried DIFFERENT materials can now
+ * collapse into a single draw call, cutting the LOD's draw-call count without changing anything
+ * visible. A no-op mesh (fewer than 2 primitives, or already all on distinct material/mode groups)
+ * costs nothing: `@gltf-transform/functions`' own `joinPrimitives` is called only per eligible group.
+ */
+export interface JoinPerMeshResult {
+    primitivesBefore: number;
+    primitivesAfter: number;
+    /** Meshes where at least one group of primitives was actually joined. */
+    meshesJoined: number;
+}
+export declare function joinPrimitivesPerMesh(document: Document): JoinPerMeshResult;

package/dist/character/stages/joinPerMesh.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinPrimitivesPerMesh = joinPrimitivesPerMesh;
+const functions_1 = require("@gltf-transform/functions");
+/** What `joinPrimitives` requires to be compatible: primitives must share a material AND draw mode. */
+function groupKey(primitive) {
+    const material = primitive.getMaterial();
+    return `${material?.getName() ?? 'none'}::${primitive.getMode()}`;
+}
+function joinPrimitivesPerMesh(document) {
+    const result = { primitivesBefore: 0, primitivesAfter: 0, meshesJoined: 0 };
+    for (const mesh of document.getRoot().listMeshes()) {
+        const primitives = mesh.listPrimitives();
+        result.primitivesBefore += primitives.length;
+        if (primitives.length < 2) {
+            result.primitivesAfter += primitives.length;
+            continue;
+        }
+        const groups = new Map();
+        for (const primitive of primitives) {
+            const key = groupKey(primitive);
+            const list = groups.get(key) ?? [];
+            list.push(primitive);
+            groups.set(key, list);
+        }
+        let meshJoined = false;
+        for (const group of groups.values()) {
+            if (group.length < 2) {
+                result.primitivesAfter += group.length;
+                continue;
+            }
+            const joined = (0, functions_1.joinPrimitives)(group);
+            for (const primitive of group) {
+                mesh.removePrimitive(primitive);
+                primitive.dispose();
+            }
+            mesh.addPrimitive(joined);
+            result.primitivesAfter += 1;
+            meshJoined = true;
+        }
+        if (meshJoined)
+            result.meshesJoined++;
+    }
+    return result;
+}
+//# sourceMappingURL=joinPerMesh.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"joinPerMesh.js","sourceRoot":"","sources":["../../../src/character/stages/joinPerMesh.ts"],"names":[],"mappings":";;AA0BA,sDA2BC;AArDD,yDAA2D;AAoB3D,uGAAuG;AACvG,SAAS,QAAQ,CAAC,SAAoB;IACpC,MAAM,QAAQ,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;IACzC,OAAO,GAAG,QAAQ,EAAE,OAAO,EAAE,IAAI,MAAM,KAAK,SAAS,CAAC,OAAO,EAAE,EAAE,CAAC;AACpE,CAAC;AAED,SAAgB,qBAAqB,CAAC,QAAkB;IACtD,MAAM,MAAM,GAAsB,EAAE,gBAAgB,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IAC/F,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC;QACnD,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QACzC,MAAM,CAAC,gBAAgB,IAAI,UAAU,CAAC,MAAM,CAAC;QAC7C,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAAC,MAAM,CAAC,eAAe,IAAI,UAAU,CAAC,MAAM,CAAC;YAAC,SAAS;QAAC,CAAC;QAErF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;QAC9C,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,MAAM,GAAG,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;YAChC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACrB,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACxB,CAAC;QAED,IAAI,UAAU,GAAG,KAAK,CAAC;QACvB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACpC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAAC,MAAM,CAAC,eAAe,IAAI,KAAK,CAAC,MAAM,CAAC;gBAAC,SAAS;YAAC,CAAC;YAC3E,MAAM,MAAM,GAAG,IAAA,0BAAc,EAAC,KAAK,CAAC,CAAC;YACrC,KAAK,MAAM,SAAS,IAAI,KAAK,EAAE,CAAC;gBAAC,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;gBAAC,SAAS,CAAC,OAAO,EAAE,CAAC;YAAC,CAAC;YACxF,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC1B,MAAM,CAAC,eAAe,IAAI,CAAC,CAAC;YAC5B,UAAU,GAAG,IAAI,CAAC;QACpB,CAAC;QACD,IAAI,UAAU;YAAE,MAAM,CAAC,YAAY,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -7,14 +7,16 @@ export interface Ktx2Result {
         name: string;
         before: number;
         after: number;
+        colorSpace: 'srgb' | 'linear';
     }[];
 }
 /**
- * Encodes the document's color textures to KTX2 / Basis (KHR_texture_basisu) via the BasisU WASM
+ * Encodes the document's textures to KTX2 / Basis (KHR_texture_basisu) via the BasisU WASM
  * encoder — GPU-compressed in VRAM (ETC1S ~6–8×, UASTC ~4×) and transcoded once at load by the
- * client's KTX2Loader. Run on the FINAL merged web GLB. The import pipeline carries a single baked
- * base-color atlas, so every remaining texture is an sRGB color/albedo map. Textures already in
- * image/ktx2 are skipped (idempotent).
+ * client's KTX2Loader. Base color and emissive maps are perceptual sRGB; normal, metallic-roughness,
+ * and occlusion maps are linear data. A source image reused across both groups is cloned before
+ * encoding because the KTX2 transfer function belongs to the image, not to an individual material
+ * slot. Textures already in image/ktx2 are skipped (idempotent).
  */
 export declare function encodeKtx2(document: Document, opts?: {
     mode?: Ktx2Mode;

package/dist/character/stages/ktx2.js

@@ -1,6 +1,4 @@
 "use strict";
-// PORTED from helix-web-engine-new/tools/character-pipeline — the source of truth for the character
-// pipeline. SYNC OBLIGATION: fix bugs there first, then mirror the change here; do not diverge.
 // Deliberate divergence (the one rewrite): the engine tool shells out to the toktx binary; the CLI
 // encodes in-process via the ktx2-encoder WASM (BasisU) so `helix character import` needs no native
 // install. Options mirror the engine's toktx flags (--encode etc1s --clevel 2 --qlevel 196 --genmipmap
@@ -42,12 +40,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.encodeKtx2 = encodeKtx2;
 const extensions_1 = require("@gltf-transform/extensions");
 const esm_1 = require("../esm");
+const imageLimits_1 = require("../imageLimits");
 /**
- * Encodes the document's color textures to KTX2 / Basis (KHR_texture_basisu) via the BasisU WASM
+ * Encodes the document's textures to KTX2 / Basis (KHR_texture_basisu) via the BasisU WASM
  * encoder — GPU-compressed in VRAM (ETC1S ~6–8×, UASTC ~4×) and transcoded once at load by the
- * client's KTX2Loader. Run on the FINAL merged web GLB. The import pipeline carries a single baked
- * base-color atlas, so every remaining texture is an sRGB color/albedo map. Textures already in
- * image/ktx2 are skipped (idempotent).
+ * client's KTX2Loader. Base color and emissive maps are perceptual sRGB; normal, metallic-roughness,
+ * and occlusion maps are linear data. A source image reused across both groups is cloned before
+ * encoding because the KTX2 transfer function belongs to the image, not to an individual material
+ * slot. Textures already in image/ktx2 are skipped (idempotent).
  */
 async function encodeKtx2(document, opts) {
     const mode = opts?.mode ?? 'etc1s';
@@ -55,32 +55,81 @@ async function encodeKtx2(document, opts) {
     const { encodeToKTX2 } = (await (0, esm_1.importEsm)('ktx2-encoder'));
     const sharp = (await Promise.resolve().then(() => __importStar(require('sharp')))).default;
     const imageDecoder = async (buf) => {
-        const { data, info } = await sharp(Buffer.from(buf)).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+        const { data, info } = await sharp(Buffer.from(buf), { limitInputPixels: imageLimits_1.MAX_CHARACTER_TEXTURE_PIXELS })
+            .ensureAlpha().raw().toBuffer({ resolveWithObject: true });
         return { width: info.width, height: info.height, data: new Uint8Array(data) };
     };
     // ETC1S: qualityLevel 1..255 (default 128). UASTC: uastcLDRQualityLevel 0..4. Faces are
     // quality-sensitive, so default ETC1S quality high; raise/switch to uastc if blocking shows.
-    const options = mode === 'uastc'
-        ? {
-            isUASTC: true,
-            uastcLDRQualityLevel: opts?.quality ?? 2,
-            needSupercompression: true,
-            generateMipmap: true,
-            isPerceptual: true,
-            isSetKTX2SRGBTransferFunc: true,
-            isKTX2File: true,
-            imageDecoder,
+    const optionsFor = (colorSpace, normalMap) => {
+        const perceptual = colorSpace === 'srgb';
+        return mode === 'uastc'
+            ? {
+                isUASTC: true,
+                uastcLDRQualityLevel: opts?.quality ?? 2,
+                needSupercompression: true,
+                generateMipmap: true,
+                isPerceptual: perceptual,
+                isSetKTX2SRGBTransferFunc: perceptual,
+                ...(normalMap ? { isNormalMap: true } : {}),
+                isKTX2File: true,
+                imageDecoder,
+            }
+            : {
+                isUASTC: false,
+                qualityLevel: opts?.quality ?? 196,
+                compressionLevel: 2,
+                generateMipmap: true,
+                isPerceptual: perceptual,
+                isSetKTX2SRGBTransferFunc: perceptual,
+                ...(normalMap ? { isNormalMap: true } : {}),
+                isKTX2File: true,
+                imageDecoder,
+            };
+    };
+    const usage = new Map();
+    const mark = (texture, kind) => {
+        if (texture === null)
+            return;
+        const current = usage.get(texture) ?? { srgb: false, linear: false, normal: false, packed: false };
+        current[kind] = true;
+        if (kind === 'normal' || kind === 'packed')
+            current.linear = true;
+        usage.set(texture, current);
+    };
+    for (const material of document.getRoot().listMaterials()) {
+        mark(material.getBaseColorTexture(), 'srgb');
+        mark(material.getEmissiveTexture(), 'srgb');
+        mark(material.getNormalTexture(), 'normal');
+        mark(material.getMetallicRoughnessTexture(), 'packed');
+        mark(material.getOcclusionTexture(), 'packed');
+    }
+    // KTX2 stores one transfer function per image. If glTF reuses one image in both
+    // color and data slots, give the linear slots their own deterministic image.
+    for (const [texture, semantics] of [...usage]) {
+        if (!semantics.srgb || !semantics.linear || texture.getMimeType() === 'image/ktx2')
+            continue;
+        const image = texture.getImage();
+        if (image === null)
+            continue;
+        const clone = document.createTexture(`${texture.getName() || 'texture'}__linear`)
+            .setImage(image)
+            .setMimeType(texture.getMimeType());
+        if (texture.getURI())
+            clone.setURI(texture.getURI());
+        usage.set(clone, { srgb: false, linear: true, normal: semantics.normal, packed: semantics.packed });
+        semantics.linear = false;
+        semantics.normal = false;
+        semantics.packed = false;
+        for (const material of document.getRoot().listMaterials()) {
+            if (material.getNormalTexture() === texture)
+                material.setNormalTexture(clone);
+            if (material.getMetallicRoughnessTexture() === texture)
+                material.setMetallicRoughnessTexture(clone);
+            if (material.getOcclusionTexture() === texture)
+                material.setOcclusionTexture(clone);
         }
-        : {
-            isUASTC: false,
-            qualityLevel: opts?.quality ?? 196,
-            compressionLevel: 2,
-            generateMipmap: true,
-            isPerceptual: true,
-            isSetKTX2SRGBTransferFunc: true,
-            isKTX2File: true,
-            imageDecoder,
-        };
+    }
     const encoded = [];
     for (const texture of document.getRoot().listTextures()) {
         if (texture.getMimeType() === 'image/ktx2')
@@ -88,8 +137,11 @@ async function encodeKtx2(document, opts) {
         const img = texture.getImage();
         if (img === null)
             continue;
-        const ktx2 = await encodeToKTX2(img, options);
-        encoded.push({ name: texture.getName() || '(unnamed)', before: img.byteLength, after: ktx2.byteLength });
+        const semantics = usage.get(texture);
+        const colorSpace = semantics?.linear && !semantics.srgb ? 'linear' : 'srgb';
+        const normalMap = colorSpace === 'linear' && semantics?.normal === true && semantics.packed === false;
+        const ktx2 = await encodeToKTX2(img, optionsFor(colorSpace, normalMap));
+        encoded.push({ name: texture.getName() || '(unnamed)', before: img.byteLength, after: ktx2.byteLength, colorSpace });
         texture.setImage(ktx2).setMimeType('image/ktx2');
     }
     return { encoder: 'basis-wasm', mode, encoded };