@ikijs/editor 0.2.1 → 0.3.1

package/README.md

@@ -56,9 +56,9 @@ leaves the document untouched.
 
 `generateIkiFromLayerSet` turns role-named layers (`face`, `eye_L`, `eye_R`,
 `mouth`, plus optional `iris_*`, `brow_*`, `lash_*`, `hair_front`, `hair_back`,
-…) into a rigged model that blinks, gazes, opens its mouth, turns its head, and
-emotes with its brows — including a hair-sway physics rig when a `hair_front`
-layer is present.
+…) into a rigged model that blinks, gazes, opens its mouth, turns its head on a
+torso that follows and breathes, and emotes with its brows — including a
+hair-sway physics rig when a `hair_front` layer is present.
 
 It takes **already-decoded** layer geometry (`LayerInput`), never pixels, which
 is what keeps this package free of any image dependency: the editor app

package/dist/index.d.mts

@@ -900,9 +900,12 @@ declare function parseLayerRoles(fileNames: string[]): {
  *   - Emit the standard parameters (same ids/ranges as sample-model.ts), plus a
  *     conditional HairSwayX descriptor + hair-sway physics rig when a hair_front
  *     layer is present.
- *   - Build headDeformer (matrix, neck pivot, AngleX+Breath bindings) and faceWarp
- *     (warp, 4×4, baked cylinder warp center-relative on faceCenterX).
- *   - Mesh parts (spec.mesh===true) → width:1, height:1, pixel grid mesh 4×4 + role bindings.
+ *   - Build headDeformer (matrix, neck pivot, AngleX+Breath bindings),
+ *     bodyDeformer when a body layer is present (matrix, torso-base pivot,
+ *     AngleX follow + Breath follow), and faceWarp (warp, FACE_GRID_CELLS²,
+ *     baked cylinder warp center-relative on faceCenterX).
+ *   - Mesh parts (spec.mesh===true) → width:1, height:1, pixel grid mesh sized by
+ *     meshCellsFor + role bindings.
  *   - Static parts (spec.mesh===false) → width:cropW, height:cropH, no mesh.
  *   - Part ids equal the role string (deterministic, no crypto.randomUUID).
  *   - Return parseIkiModel(structuredClone(model)) — every caller gets a

package/dist/index.d.ts

@@ -900,9 +900,12 @@ declare function parseLayerRoles(fileNames: string[]): {
  *   - Emit the standard parameters (same ids/ranges as sample-model.ts), plus a
  *     conditional HairSwayX descriptor + hair-sway physics rig when a hair_front
  *     layer is present.
- *   - Build headDeformer (matrix, neck pivot, AngleX+Breath bindings) and faceWarp
- *     (warp, 4×4, baked cylinder warp center-relative on faceCenterX).
- *   - Mesh parts (spec.mesh===true) → width:1, height:1, pixel grid mesh 4×4 + role bindings.
+ *   - Build headDeformer (matrix, neck pivot, AngleX+Breath bindings),
+ *     bodyDeformer when a body layer is present (matrix, torso-base pivot,
+ *     AngleX follow + Breath follow), and faceWarp (warp, FACE_GRID_CELLS²,
+ *     baked cylinder warp center-relative on faceCenterX).
+ *   - Mesh parts (spec.mesh===true) → width:1, height:1, pixel grid mesh sized by
+ *     meshCellsFor + role bindings.
  *   - Static parts (spec.mesh===false) → width:cropW, height:cropH, no mesh.
  *   - Part ids equal the role string (deterministic, no crypto.randomUUID).
  *   - Return parseIkiModel(structuredClone(model)) — every caller gets a

package/dist/index.js

@@ -1668,11 +1668,12 @@ var ROLE_TABLE = {
   // the turn through its own part warp (bakeHairBackTurnWarp) and swings its
   // ends on the hair-sway warps.
   hair_back: { deformer: "headDeformer", order: 0, mesh: true },
-  // The torso. Alone among the roles it hangs from NO deformer: the head turns
-  // about the neck pivot while the shoulders stay put, which is what keeps the
-  // character from reading as a floating head. Drawn over the back hair so long
-  // hair falls behind the shoulders.
-  body: { deformer: "none", order: 5, mesh: false },
+  // The torso. It rides its own rigid deformer, not the head's: the head turns
+  // about the neck pivot while the shoulders follow at BODY_TURN_FOLLOW and
+  // follow the head's breath bob, which is what keeps the character from
+  // reading as a floating head. Drawn over the back hair so long hair falls
+  // behind the shoulders.
+  body: { deformer: "bodyDeformer", order: 5, mesh: false },
   face: { deformer: "faceWarp", order: 10, mesh: true },
   nose: { deformer: "faceWarp", order: 15, mesh: true },
   blush_L: { deformer: "faceWarp", order: 20, mesh: true },
@@ -1833,8 +1834,20 @@ function createPixelGridMesh(cols, rows, w, h) {
   }
   return { vertices, uvs, indices };
 }
+var MESH_CELL_PX = 64;
+var MESH_CELLS_MIN = 4;
+var MESH_CELLS_MAX = 8;
+function meshCellsFor(w, h) {
+  const cells = (px) => Math.max(
+    MESH_CELLS_MIN,
+    Math.min(MESH_CELLS_MAX, Math.round(px / MESH_CELL_PX))
+  );
+  return { cols: cells(w), rows: cells(h) };
+}
+var FACE_GRID_CELLS = 6;
 var HEAD_CYLINDER_RADIUS_FACTOR = 0.6 / 0.5;
 var HEAD_TURN_MAX_DEG = 30;
+var HEAD_TURN_STOPS = [-30, -15, 0, 15, 30];
 function headTurnParallaxUnit(gridHalfWidth) {
   return gridHalfWidth * HEAD_CYLINDER_RADIUS_FACTOR * Math.sin(HEAD_TURN_MAX_DEG * (Math.PI / 180));
 }
@@ -1850,7 +1863,7 @@ function pinnedCylinderBend(local, radius, theta) {
   return radius * Math.sin(alpha + theta) - local - radius * Math.sin(theta);
 }
 function bakeHeadTurnGridWarp2DCentered(grid, parameterX, parameterY, centerX, centerY) {
-  const STOPS = [-HEAD_TURN_MAX_DEG, 0, HEAD_TURN_MAX_DEG];
+  const STOPS = [...HEAD_TURN_STOPS];
   const RADIUS_X = gridReach(grid, 0, centerX) * HEAD_CYLINDER_RADIUS_FACTOR;
   const RADIUS_Y = gridReach(grid, 1, centerY) * HEAD_CYLINDER_RADIUS_FACTOR;
   const pointCount = grid.points.length / 2;
@@ -1990,16 +2003,17 @@ function bindingsForRole(spec, role, cropW, cropH, options = {}) {
   }
   if (role === "hair_front" || role === "hair_back") {
     const isFront = role === "hair_front";
-    const depth = isFront ? HAIR_FRONT_DEPTH : HAIR_BACK_DEPTH;
     const parallax = [];
-    const shiftX = depth * (options.parallaxUnit ?? 0);
-    if (shiftX !== 0) {
-      parallax.push({
-        parameter: import_format3.StandardParameter.AngleX,
-        channel: "translateX",
-        from: -shiftX,
-        to: shiftX
-      });
+    if (!isFront) {
+      const shiftX = HAIR_BACK_DEPTH * (options.parallaxUnit ?? 0);
+      if (shiftX !== 0) {
+        parallax.push({
+          parameter: import_format3.StandardParameter.AngleX,
+          channel: "translateX",
+          from: -shiftX,
+          to: shiftX
+        });
+      }
     }
     const shiftY = (isFront ? 0 : HAIR_BACK_NOD_DEPTH) * (options.parallaxUnitY ?? 0);
     if (shiftY !== 0) {
@@ -2046,14 +2060,18 @@ function bakeHairBackTurnWarp(mesh, parameter) {
   const radius = halfWidth * HAIR_BACK_BEND_RADIUS_FACTOR;
   const bulge = HAIR_BACK_FAR_BULGE * halfWidth;
   const DEG_TO_RAD = Math.PI / 180;
-  const keyforms = [-HEAD_TURN_MAX_DEG, 0, HEAD_TURN_MAX_DEG].map((deg) => {
+  const keyforms = HEAD_TURN_STOPS.map((deg) => {
     const theta = deg * DEG_TO_RAD;
     const s = Math.sign(deg);
+    const turnFraction = Math.abs(deg) / HEAD_TURN_MAX_DEG;
+    const fullTheta = s * HEAD_TURN_MAX_DEG * DEG_TO_RAD;
+    const bulgeAtStop = bulge * deg / HEAD_TURN_MAX_DEG;
     const offsets = [];
     for (let i = 0; i < mesh.vertices.length; i += 2) {
       const x = mesh.vertices[i];
       const far = Math.max(0, -s * x / halfWidth);
-      offsets.push(pinnedCylinderBend(x, radius, theta) - s * bulge * far, 0);
+      const bend = far > 0 ? turnFraction * pinnedCylinderBend(x, radius, fullTheta) : pinnedCylinderBend(x, radius, theta);
+      offsets.push(bend - bulgeAtStop * far, 0);
     }
     return { value: deg, offsets };
   });
@@ -2085,10 +2103,15 @@ function bakeHairSwayWarp(mesh, parameter, tipShift, range) {
     ]
   };
 }
+var HEAD_TURN_TRAVEL = 50;
+var BODY_TURN_FOLLOW = 0.3;
+var HEAD_BREATH_BOB = -12;
+var BODY_BREATH_FOLLOW = 0.5;
 function generateIkiFromLayerSet(layers, canvas) {
   validateLayerInputs(layers, canvas);
   const hasHair = layers.some((l) => l.role === "hair_front");
   const hasMouthOpen = layers.some((l) => l.role === "mouth_open");
+  const bodyLayer = layers.find((l) => l.role === "body");
   const parameters = [
     {
       id: import_format3.StandardParameter.MouthOpen,
@@ -2252,11 +2275,11 @@ function generateIkiFromLayerSet(layers, canvas) {
   const faceGridMinX = faceCenterX - halfW;
   const faceGridMaxX = faceCenterX + halfW;
   const faceGrid = {
-    cols: 4,
-    rows: 4,
+    cols: FACE_GRID_CELLS,
+    rows: FACE_GRID_CELLS,
     points: generateGridPoints(
-      4,
-      4,
+      FACE_GRID_CELLS,
+      FACE_GRID_CELLS,
       faceGridMinX,
       faceGridMaxX,
       unionMinY,
@@ -2287,21 +2310,20 @@ function generateIkiFromLayerSet(layers, canvas) {
       id: "headDeformer",
       pivot: neckPivot,
       bindings: [
-        {
-          parameter: import_format3.StandardParameter.AngleX,
-          channel: "rotate",
-          from: 6,
-          to: -6
-        },
+        // The turn is a pure yaw: no roll rides on AngleX. The sample model's
+        // ±6° "lean into the turn" was tried here and dropped — rotating about
+        // the neck pivot swings the crown (~500px above it) far more than the
+        // chin, so the top of the head appeared to lunge ahead of the face on
+        // every turn. Roll is AngleZ's job, below.
         {
           parameter: import_format3.StandardParameter.AngleX,
           channel: "translateX",
-          from: -50,
-          to: 50
+          from: -HEAD_TURN_TRAVEL,
+          to: HEAD_TURN_TRAVEL
         },
         // Nod: a vertical translate only. No rotate — a pitch expressed as a
-        // rigid rotation would sum with the roll below at diagonal poses,
-        // collapsing pitch into roll.
+        // rigid rotation would sum with the AngleZ roll below at diagonal
+        // poses, collapsing pitch into roll.
         {
           parameter: import_format3.StandardParameter.AngleY,
           channel: "translateY",
@@ -2310,10 +2332,10 @@ function generateIkiFromLayerSet(layers, canvas) {
         },
         // Tilt: the whole head rolls about the neck pivot, one degree per
         // degree. Positive AngleZ is clockwise on screen (engine rotate is
-        // CCW-positive, hence the flipped from/to) — Live2D's convention, and
-        // the same sense as the lean above: in Live2D's own sample motions
-        // AngleZ carries the sign of AngleX 214 times out of 222. The two
-        // rotations sum, which is correct for two rolls about one pivot.
+        // CCW-positive, hence the flipped from/to) — Live2D's convention: in
+        // its own sample motions AngleZ carries the sign of AngleX 214 times
+        // out of 222, i.e. a head that leans into its turn tilts clockwise on
+        // a turn to the viewer's right. The only rotate binding on the head.
         {
           parameter: import_format3.StandardParameter.AngleZ,
           channel: "rotate",
@@ -2324,7 +2346,7 @@ function generateIkiFromLayerSet(layers, canvas) {
           parameter: import_format3.StandardParameter.Breath,
           channel: "translateY",
           from: 0,
-          to: -12
+          to: HEAD_BREATH_BOB
         }
       ]
     },
@@ -2340,6 +2362,34 @@ function generateIkiFromLayerSet(layers, canvas) {
       warp2d: faceWarp2d
     }
   ];
+  if (bodyLayer) {
+    const bt = bboxToTransform(
+      bodyLayer.bbox,
+      bodyLayer.canvasW,
+      bodyLayer.canvasH,
+      "body"
+    );
+    deformers.push({
+      id: "bodyDeformer",
+      pivot: { x: bt.x, y: bt.y - bodyLayer.cropH / 2 },
+      bindings: [
+        // Low-weight follow of the turn, same direction as the head.
+        {
+          parameter: import_format3.StandardParameter.AngleX,
+          channel: "translateX",
+          from: -BODY_TURN_FOLLOW * HEAD_TURN_TRAVEL,
+          to: BODY_TURN_FOLLOW * HEAD_TURN_TRAVEL
+        },
+        // Breath: follow the head's bob, same direction, half amplitude.
+        {
+          parameter: import_format3.StandardParameter.Breath,
+          channel: "translateY",
+          from: 0,
+          to: BODY_BREATH_FOLLOW * HEAD_BREATH_BOB
+        }
+      ]
+    });
+  }
   const eyeCreaseBySide = {};
   for (const layer of layers) {
     const side = ROLE_TABLE[layer.role].eyeSide;
@@ -2364,7 +2414,8 @@ function generateIkiFromLayerSet(layers, canvas) {
     });
     const deformerId = spec.deformer === "none" ? void 0 : spec.deformer;
     if (spec.mesh) {
-      const mesh = createPixelGridMesh(4, 4, cropW, cropH);
+      const { cols, rows } = meshCellsFor(cropW, cropH);
+      const mesh = createPixelGridMesh(cols, rows, cropW, cropH);
       const part = {
         id: role,
         color: [1, 1, 1, 1],
@@ -2380,6 +2431,7 @@ function generateIkiFromLayerSet(layers, canvas) {
       }
       if ((role === "hair_front" || role === "hair_back") && hasHair) {
         let tipShift = HAIR_SWAY_TIP_FRACTION * cropH;
+        let leadWarp;
         if (role === "hair_front") {
           const shift = HAIR_FRONT_DEPTH * parallaxUnit;
           const headroom = Math.min(
@@ -2390,6 +2442,12 @@ function generateIkiFromLayerSet(layers, canvas) {
             tipShift,
             Math.max(0, headroom) / HAIR_SWAY_PEAK_FRACTION
           );
+          leadWarp = bakeHairSwayWarp(
+            mesh,
+            import_format3.StandardParameter.AngleX,
+            shift,
+            HEAD_TURN_MAX_DEG
+          );
         }
         part.warps = [
           bakeHairSwayWarp(
@@ -2403,7 +2461,8 @@ function generateIkiFromLayerSet(layers, canvas) {
             import_format3.StandardParameter.HairSwayZ,
             tipShift,
             HAIR_SWAY_RANGE
-          )
+          ),
+          ...leadWarp ? [leadWarp] : []
         ];
       }
       if (role === "hair_back") {