@ikijs/editor 0.31.0 → 0.32.0

package/README.md

@@ -102,7 +102,8 @@ hair sway), validated against `RIG_PLAN_FIELDS`. `options.patches` adds displace
 stops (`RigPatch`), replayed on every rig and reported through
 `options.onPatchesApplied`; a refused op throws `PatchError`. `options.customParts` adds parts the
 auto-rigger has no role for (`CustomPart`: `id`, `layer`, `anchor`, `tie`,
-`after`), unrigged on `headDeformer` with a plain mesh and drawn after the
+`after`, and `occlusion`: roles whose parts hide it by an amount keyed on a
+parameter), unrigged on `headDeformer` with a plain mesh and drawn after the
 `after` role's last part; the rest of the model is as without them but for
 the `order` of every part after an inserted one (a set rigged without
 `customParts` is byte-identical), and a malformed entry throws

package/dist/index.d.mts

@@ -251,10 +251,11 @@ declare class AddDeformer implements EditCommand {
  * visually predictable.
  *
  * No `parseIkiModel` pre-check is needed: removing an element from an already-
- * valid model cannot introduce a structural violation — EXCEPT for clip-mask
- * references, the one part→part reference in the contract. `apply` refuses to
- * delete a part still used as another part's `clip.masks` entry (guard below),
- * so it can never leave a dangling mask ref that would fail `toIkiModel()`.
+ * valid model cannot introduce a structural violation — EXCEPT for the part→part
+ * references in the contract: `clip.masks` and `occlusion.by`. `apply` refuses to
+ * delete a part still used as another part's `clip.masks` or `occlusion.by`
+ * entry (guards below), so it can never leave a dangling ref that would fail
+ * `toIkiModel()`.
  *
  * Texture-reference safety (package invariant): `apply` refuses to delete a
  * part that still carries `part.texture`. Texture/atlas state is non-undoable
@@ -1081,6 +1082,19 @@ interface CustomPart {
     /** The art does not bend (a hairpin, a ribbon): a bake that bends it more
      *  than 0.0025 face widths at a stop is refused (`BakeError`). */
     rigid?: boolean;
+    /** Hide the part where the parts of these roles cover it, by an amount keyed on a
+     *  parameter (`IkiPart.occlusion`). `by` lists roles of the set: the
+     *  generator writes the part ids those roles yield. The parameter is one
+     *  the model declares and not a physics output; the stops follow the
+     *  format's rules. */
+    occlusion?: {
+        by: string[];
+        parameter: string;
+        stops: {
+            value: number;
+            amount: number;
+        }[];
+    };
 }
 /** A `customParts` entry that is malformed or misses the layer set. Its
  *  message starts `customParts[i].<field>` (`customParts` alone for a
@@ -1917,10 +1931,11 @@ declare function validateDeformerReparent(deformers: IkiDeformer[], deformerId:
  * `toIkiModel()` refuses.
  *
  * Note: there is no validatePartDelete here, but NOT because parts are
- * unreferenced — `clip.masks` names parts by id. That invariant is enforced
- * closer to the edits that could break it: `DeletePart` refuses to remove a
- * part still used as a mask, and `SetPartMesh` refuses to strip the mesh off
- * one (masks must be mesh parts). No command creates or edits `clip`.
+ * unreferenced — `clip.masks` and `occlusion.by` name parts by id. That
+ * invariant is enforced closer to the edits that could break it: `DeletePart`
+ * refuses to remove a part still used as a mask or an occluder, and
+ * `SetPartMesh` refuses to strip the mesh off one (both must be mesh parts).
+ * No command creates or edits `clip` or `occlusion`.
  */
 declare function validateDeformerDelete(deformers: IkiDeformer[], parts: IkiPart[], physicsChains: IkiPhysicsChain[], deformerId: string): void;
 /**

package/dist/index.d.ts

@@ -251,10 +251,11 @@ declare class AddDeformer implements EditCommand {
  * visually predictable.
  *
  * No `parseIkiModel` pre-check is needed: removing an element from an already-
- * valid model cannot introduce a structural violation — EXCEPT for clip-mask
- * references, the one part→part reference in the contract. `apply` refuses to
- * delete a part still used as another part's `clip.masks` entry (guard below),
- * so it can never leave a dangling mask ref that would fail `toIkiModel()`.
+ * valid model cannot introduce a structural violation — EXCEPT for the part→part
+ * references in the contract: `clip.masks` and `occlusion.by`. `apply` refuses to
+ * delete a part still used as another part's `clip.masks` or `occlusion.by`
+ * entry (guards below), so it can never leave a dangling ref that would fail
+ * `toIkiModel()`.
  *
  * Texture-reference safety (package invariant): `apply` refuses to delete a
  * part that still carries `part.texture`. Texture/atlas state is non-undoable
@@ -1081,6 +1082,19 @@ interface CustomPart {
     /** The art does not bend (a hairpin, a ribbon): a bake that bends it more
      *  than 0.0025 face widths at a stop is refused (`BakeError`). */
     rigid?: boolean;
+    /** Hide the part where the parts of these roles cover it, by an amount keyed on a
+     *  parameter (`IkiPart.occlusion`). `by` lists roles of the set: the
+     *  generator writes the part ids those roles yield. The parameter is one
+     *  the model declares and not a physics output; the stops follow the
+     *  format's rules. */
+    occlusion?: {
+        by: string[];
+        parameter: string;
+        stops: {
+            value: number;
+            amount: number;
+        }[];
+    };
 }
 /** A `customParts` entry that is malformed or misses the layer set. Its
  *  message starts `customParts[i].<field>` (`customParts` alone for a
@@ -1917,10 +1931,11 @@ declare function validateDeformerReparent(deformers: IkiDeformer[], deformerId:
  * `toIkiModel()` refuses.
  *
  * Note: there is no validatePartDelete here, but NOT because parts are
- * unreferenced — `clip.masks` names parts by id. That invariant is enforced
- * closer to the edits that could break it: `DeletePart` refuses to remove a
- * part still used as a mask, and `SetPartMesh` refuses to strip the mesh off
- * one (masks must be mesh parts). No command creates or edits `clip`.
+ * unreferenced — `clip.masks` and `occlusion.by` name parts by id. That
+ * invariant is enforced closer to the edits that could break it: `DeletePart`
+ * refuses to remove a part still used as a mask or an occluder, and
+ * `SetPartMesh` refuses to strip the mesh off one (both must be mesh parts).
+ * No command creates or edits `clip` or `occlusion`.
  */
 declare function validateDeformerDelete(deformers: IkiDeformer[], parts: IkiPart[], physicsChains: IkiPhysicsChain[], deformerId: string): void;
 /**

package/dist/index.js

@@ -1115,6 +1115,14 @@ var DeletePart = class {
         `parts."${this.partId}": cannot delete \u2014 used as a clip mask by part "${masker.id}"; remove its clip first`
       );
     }
+    const occluded = parts.find(
+      (p) => p.id !== this.partId && p.occlusion?.by.includes(this.partId)
+    );
+    if (occluded) {
+      throw new Error(
+        `parts."${this.partId}": cannot delete \u2014 used as an occluder by part "${occluded.id}"; remove its occlusion first`
+      );
+    }
     const i = parts.indexOf(part);
     if (!this.captured) {
       this.removed = structuredClone(part);
@@ -1319,6 +1327,14 @@ var SetPartMesh = class {
           `parts."${this.partId}": cannot remove mesh \u2014 used as a clip mask by part "${masker.id}" (masks require a mesh); remove its clip first`
         );
       }
+      const occluded = doc.getModel().parts.find(
+        (p) => p.id !== this.partId && p.occlusion?.by.includes(this.partId)
+      );
+      if (occluded) {
+        throw new import_format2.IkiFormatError(
+          `parts."${this.partId}": cannot remove mesh \u2014 used as an occluder by part "${occluded.id}" (occluders require a mesh); remove its occlusion first`
+        );
+      }
     } else {
       if ((part.warps?.length ?? 0) > 0) {
         throw new import_format2.IkiFormatError(
@@ -1398,6 +1414,14 @@ function validatePhysicsCandidate(doc, candidatePhysics) {
     }
     throw e;
   }
+  for (const rig of candidatePhysics) {
+    const part = doc.getModel().parts.find((p) => p.occlusion?.parameter === rig.output.parameter);
+    if (part !== void 0) {
+      throw new import_format2.IkiFormatError(
+        `physics."${rig.id}".output.parameter "${rig.output.parameter}" keys parts."${part.id}".occlusion; an occlusion amount cannot be keyed on a physics output`
+      );
+    }
+  }
 }
 var AddPhysicsRig = class {
   label = "Add physics rig";
@@ -7132,7 +7156,18 @@ function span2(name, v) {
 }
 
 // src/auto-rig/custom-parts.ts
-var KEYS = ["id", "layer", "anchor", "tie", "after", "deformer", "rigid"];
+var KEYS = [
+  "id",
+  "layer",
+  "anchor",
+  "tie",
+  "after",
+  "deformer",
+  "rigid",
+  "occlusion"
+];
+var OCCLUSION_KEYS = ["by", "parameter", "stops"];
+var STOP_KEYS = ["value", "amount"];
 var LAYER_KEYS = ["fileName", "bbox"];
 var finite4 = (v) => typeof v === "number" && Number.isFinite(v);
 var isObject3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
@@ -7140,7 +7175,7 @@ var inside = (b, [x, y]) => x >= b.x && x < b.x + b.w && y >= b.y && y < b.y + b
 var RESERVED = new Set(
   ROLE_TABLE.flatMap((r) => [r.role, ...partIdsOfRole(r.role)])
 );
-function checkCustomParts(customParts, byRole, canvas) {
+function checkCustomParts(customParts, byRole, canvas, parameters, physicsOutputs) {
   if (!Array.isArray(customParts)) {
     throw new CustomPartError(
       `customParts must be an array, got ${customParts === null ? "null" : typeof customParts}`
@@ -7163,7 +7198,7 @@ function checkCustomParts(customParts, byRole, canvas) {
       throw new CustomPartError(`${at} must be a plain object`);
     }
     checkedKeys(at, entry, KEYS, CustomPartError);
-    const { id, layer, anchor, tie, after, deformer, rigid } = entry;
+    const { id, layer, anchor, tie, after, deformer, rigid, occlusion } = entry;
     if (typeof id !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(id)) {
       throw new CustomPartError(
         `${at}.id must be a plain identifier (letters, digits, underscore; not starting with a digit), got ${JSON.stringify(id)}`
@@ -7214,9 +7249,84 @@ function checkCustomParts(customParts, byRole, canvas) {
         `${at}.rigid must be true or false, got ${JSON.stringify(rigid)}`
       );
     }
+    if (occlusion !== void 0) {
+      checkOcclusion(
+        `${at}.occlusion`,
+        occlusion,
+        present,
+        parameters,
+        physicsOutputs
+      );
+    }
   });
   return customParts;
 }
+function checkOcclusion(at, occlusion, present, parameters, physicsOutputs) {
+  if (!isObject3(occlusion)) {
+    throw new CustomPartError(`${at} must be a plain object`);
+  }
+  checkedKeys(at, occlusion, OCCLUSION_KEYS, CustomPartError);
+  const { by, parameter, stops } = occlusion;
+  if (!Array.isArray(by) || by.length === 0) {
+    throw new CustomPartError(
+      `${at}.by must be a non-empty array of roles of the set, one of ${present.join(", ")}`
+    );
+  }
+  by.forEach((role, j) => {
+    if (typeof role !== "string" || !present.includes(role)) {
+      throw new CustomPartError(
+        `${at}.by[${j}] must be a role of the set, one of ${present.join(", ")}; got ${JSON.stringify(role)}`
+      );
+    }
+    if (by.indexOf(role) !== j) {
+      throw new CustomPartError(
+        `${at}.by[${j}] "${role}" repeats an earlier role`
+      );
+    }
+  });
+  const descriptor = parameters.find((p) => p.id === parameter);
+  if (typeof parameter !== "string" || descriptor === void 0) {
+    throw new CustomPartError(
+      `${at}.parameter must be a parameter the rig declares, got ${JSON.stringify(parameter)}`
+    );
+  }
+  if (physicsOutputs.has(parameter)) {
+    throw new CustomPartError(
+      `${at}.parameter "${parameter}" is a physics output; an occlusion amount cannot be keyed on one`
+    );
+  }
+  if (!Array.isArray(stops) || stops.length === 0) {
+    throw new CustomPartError(`${at}.stops must be a non-empty array`);
+  }
+  const { min, max } = descriptor;
+  let previous = -Infinity;
+  stops.forEach((stop, k) => {
+    const s = `${at}.stops[${k}]`;
+    if (!isObject3(stop))
+      throw new CustomPartError(`${s} must be a plain object`);
+    checkedKeys(s, stop, STOP_KEYS, CustomPartError);
+    const { value, amount } = stop;
+    if (!finite4(value)) {
+      throw new CustomPartError(
+        `${s}.value must be a finite number, got ${JSON.stringify(value)}`
+      );
+    }
+    if (value < min || value > max) {
+      throw new CustomPartError(
+        `${s}.value ${value} is outside parameter "${parameter}" range [${min},${max}]`
+      );
+    }
+    if (value <= previous) {
+      throw new CustomPartError(`${s}.value must be strictly ascending`);
+    }
+    previous = value;
+    if (!finite4(amount) || amount < 0 || amount > 1) {
+      throw new CustomPartError(
+        `${s}.amount must be a number in 0..1, got ${JSON.stringify(amount)}`
+      );
+    }
+  });
+}
 var CELL_PX2 = 20;
 function buildCustomParts(customParts, canvas) {
   return customParts.map(({ id, layer }) => {
@@ -7236,6 +7346,32 @@ function buildCustomParts(customParts, canvas) {
     };
   });
 }
+function writeOcclusion(customParts, built, parts) {
+  const byId = new Map(parts.map((p) => [p.id, p]));
+  customParts.forEach((entry, i) => {
+    if (entry.occlusion === void 0) return;
+    const { by, parameter, stops } = entry.occlusion;
+    const ids = [];
+    by.forEach((role, j) => {
+      for (const id of partIdsOfRole(role)) {
+        const part = byId.get(id);
+        if (part === void 0) continue;
+        const fault = part.clip !== void 0 ? { is: "is clipped", kind: "a clipped part" } : part.mesh === void 0 ? { is: "has no mesh", kind: "a part without a mesh" } : void 0;
+        if (fault !== void 0) {
+          throw new CustomPartError(
+            `customParts[${i}].occlusion.by[${j}] "${role}" yields part "${id}", which ${fault.is}; ${fault.kind} cannot occlude`
+          );
+        }
+        ids.push(id);
+      }
+    });
+    built[i].occlusion = {
+      by: ids,
+      parameter,
+      stops: stops.map((s) => ({ value: s.value, amount: s.amount }))
+    };
+  });
+}
 
 // src/auto-rig/generate.ts
 var MESH_CELLS = {
@@ -7278,8 +7414,15 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
   const hasNose = has("nose");
   const plateHalf = byRole.get("face").cropW / 2;
   checkHeadEdges(options.headEdges, byRole);
-  const entries = options.customParts !== void 0 && !(Array.isArray(options.customParts) && options.customParts.length === 0) ? checkCustomParts(options.customParts, byRole, canvas) : [];
+  const physics = has("hair_front") ? hairPhysics(has("hair_back")) : void 0;
   const parameters = declareParameters(new Set(byRole.keys()));
+  const entries = options.customParts !== void 0 && !(Array.isArray(options.customParts) && options.customParts.length === 0) ? checkCustomParts(
+    options.customParts,
+    byRole,
+    canvas,
+    parameters,
+    new Set((physics ?? []).map((r) => r.output.parameter))
+  ) : [];
   const bakes = options.bakes === void 0 ? void 0 : parseBakes(options.bakes, entries, parameters);
   checkStrandEdges(
     options.strandEdges,
@@ -7460,6 +7603,7 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
     parts.forEach((p, i) => {
       p.order = i;
     });
+    writeOcclusion(entries, built, parts);
     if (bakes !== void 0) {
       bakeReports = applyBakes(bakes, built, entries, {
         canvas,
@@ -7476,7 +7620,7 @@ function generateIkiFromLayerSet(layers, canvas, options = {}) {
     parameters,
     parts,
     deformers: deformerList,
-    ...has("hair_front") ? { physics: hairPhysics(has("hair_back")) } : {},
+    ...physics !== void 0 ? { physics } : {},
     expressions: defaultExpressions(new Set(parameters.map((p) => p.id))),
     motions: defaultMotions(new Set(parameters.map((p) => p.id)))
   };