@zephyr3d/scene 0.9.1 → 0.9.3

package/dist/animation/joint_dynamics/constraints.js.map

@@ -1 +1 @@
-{"version":3,"file":"constraints.js","sources":["../../../src/animation/joint_dynamics/constraints.ts"],"sourcesContent":["// Constraint creation utilities — port of SPCRJointDynamicsController constraint building\r\n\r\nimport { Vector3 } from '@zephyr3d/base';\r\nimport { ConstraintType, type Constraint, type BoneNode } from './types';\r\n\r\n/** Options for constraint generation from bone hierarchy */\r\nexport interface ConstraintBuildOptions {\r\n  /** Generate parent→child vertical constraints */\r\n  structuralVertical: boolean;\r\n  /** Generate same-depth horizontal constraints across chains */\r\n  structuralHorizontal: boolean;\r\n  /** Generate diagonal cross-bracing constraints */\r\n  shear: boolean;\r\n  /** Generate skip-one vertical bending constraints */\r\n  bendingVertical: boolean;\r\n  /** Generate skip-one horizontal bending constraints */\r\n  bendingHorizontal: boolean;\r\n  /** Connect last root point back to first (for cylindrical topology like skirts) */\r\n  isLoop: boolean;\r\n  /** Enable per-constraint collision detection on structural vertical pairs */\r\n  collideStructuralVertical: boolean;\r\n  /** Enable per-constraint collision detection on structural horizontal pairs */\r\n  collideStructuralHorizontal: boolean;\r\n  /** Enable per-constraint collision detection on shear pairs */\r\n  collideShear: boolean;\r\n  /** Enable surface/triangle collision (overrides per-type collision flags) */\r\n  enableSurfaceCollision: boolean;\r\n}\r\n\r\ninterface RawConstraint {\r\n  type: ConstraintType;\r\n  indexA: number;\r\n  indexB: number;\r\n  length: number;\r\n}\r\n\r\nfunction getFirstChild(node: BoneNode): BoneNode | null {\r\n  return node.children.length > 0 ? node.children[0] : null;\r\n}\r\n\r\nfunction constraintLength(a: BoneNode, b: BoneNode): number {\r\n  return Vector3.distance(a.position, b.position);\r\n}\r\n\r\n// ── Structural Vertical: parent→child chains ──\r\n\r\nfunction createStructuralVertical(node: BoneNode, out: RawConstraint[]) {\r\n  for (const child of node.children) {\r\n    out.push({\r\n      type: ConstraintType.Structural_Vertical,\r\n      indexA: node.index,\r\n      indexB: child.index,\r\n      length: constraintLength(node, child)\r\n    });\r\n    createStructuralVertical(child, out);\r\n  }\r\n}\r\n\r\n// ── Structural Horizontal: same-depth siblings across chains ──\r\n\r\nfunction createHorizontal(\r\n  a: BoneNode | null,\r\n  b: BoneNode | null,\r\n  type: ConstraintType,\r\n  out: RawConstraint[]\r\n) {\r\n  if (!a || !b || a === b) {\r\n    return;\r\n  }\r\n  const childA = getFirstChild(a);\r\n  const childB = getFirstChild(b);\r\n\r\n  if (childA && childB) {\r\n    out.push({\r\n      type,\r\n      indexA: childA.index,\r\n      indexB: childB.index,\r\n      length: constraintLength(childA, childB)\r\n    });\r\n    createHorizontal(childA, childB, type, out);\r\n  } else if (childA && !childB) {\r\n    out.push({\r\n      type,\r\n      indexA: childA.index,\r\n      indexB: b.index,\r\n      length: constraintLength(childA, b)\r\n    });\r\n  } else if (!childA && childB) {\r\n    out.push({\r\n      type,\r\n      indexA: a.index,\r\n      indexB: childB.index,\r\n      length: constraintLength(a, childB)\r\n    });\r\n  }\r\n}\r\n\r\n// ── Shear: diagonal cross-bracing ──\r\n\r\nfunction createShear(a: BoneNode | null, b: BoneNode | null, out: RawConstraint[]) {\r\n  if (!a || !b || a === b) {\r\n    return;\r\n  }\r\n  const cA = getFirstChild(a);\r\n  const cB = getFirstChild(b);\r\n  const cA2 = cA ? getFirstChild(cA) : null;\r\n  const cB2 = cB ? getFirstChild(cB) : null;\r\n  const cA3 = cA2 ? getFirstChild(cA2) : null;\r\n  const cB3 = cB2 ? getFirstChild(cB2) : null;\r\n\r\n  const target1 = cA ?? cA2 ?? cA3;\r\n  if (target1) {\r\n    out.push({\r\n      type: ConstraintType.Shear,\r\n      indexA: target1.index,\r\n      indexB: b.index,\r\n      length: constraintLength(target1, b)\r\n    });\r\n  }\r\n\r\n  const target2 = cB ?? cB2 ?? cB3;\r\n  if (target2) {\r\n    out.push({\r\n      type: ConstraintType.Shear,\r\n      indexA: a.index,\r\n      indexB: target2.index,\r\n      length: constraintLength(a, target2)\r\n    });\r\n  }\r\n\r\n  createShear(cA, cB, out);\r\n}\r\n\r\n// ── Bending Vertical: skip-one (grandparent→grandchild) ──\r\n\r\nfunction createBendingVertical(node: BoneNode, out: RawConstraint[]) {\r\n  if (node.children.length !== 1) {\r\n    return;\r\n  }\r\n  const childA = node.children[0];\r\n  if (childA.children.length !== 1) {\r\n    return;\r\n  }\r\n  const childB = childA.children[0];\r\n\r\n  out.push({\r\n    type: ConstraintType.Bending_Vertical,\r\n    indexA: node.index,\r\n    indexB: childB.index,\r\n    length: constraintLength(node, childB)\r\n  });\r\n  createBendingVertical(childA, out);\r\n}\r\n\r\n// ── Constraint grouping (no shared point indices per group) ──\r\n\r\nfunction findSameIndex(group: Constraint[], c: Constraint): boolean {\r\n  for (const g of group) {\r\n    if (g.indexA === c.indexA || g.indexA === c.indexB || g.indexB === c.indexA || g.indexB === c.indexB) {\r\n      return true;\r\n    }\r\n  }\r\n  return false;\r\n}\r\n\r\nfunction pushToGroups(groups: Constraint[][], c: Constraint) {\r\n  for (const g of groups) {\r\n    if (!findSameIndex(g, c)) {\r\n      g.push(c);\r\n      return;\r\n    }\r\n  }\r\n  groups.push([c]);\r\n}\r\n\r\n// ── Surface faces (quads → 2 triangles of 3 indices) ──\r\n\r\nfunction createSurfaceFaces(a: BoneNode | null, b: BoneNode | null, out: number[]) {\r\n  if (!a || !b || a === b) {\r\n    return;\r\n  }\r\n  const cA = getFirstChild(a);\r\n  const cB = getFirstChild(b);\r\n  if (cA && cB) {\r\n    if (\r\n      a.useForSurfaceCollision !== false &&\r\n      b.useForSurfaceCollision !== false &&\r\n      cA.useForSurfaceCollision !== false &&\r\n      cB.useForSurfaceCollision !== false\r\n    ) {\r\n      // Quad ABCD → triangles ABC, CDA\r\n      out.push(a.index, b.index, cB.index, cB.index, cA.index, a.index);\r\n    }\r\n    createSurfaceFaces(cA, cB, out);\r\n  }\r\n}\r\n\r\n// ── Public API ──\r\n\r\nexport function buildConstraints(rootPoints: BoneNode[], options: ConstraintBuildOptions): Constraint[] {\r\n  const n = rootPoints.length;\r\n  const groups: Constraint[][] = [];\r\n\r\n  const addRaw = (raws: RawConstraint[], collide: boolean) => {\r\n    for (const r of raws) {\r\n      const bothFixed = isBoneFixed(rootPoints, r.indexA) && isBoneFixed(rootPoints, r.indexB);\r\n      pushToGroups(groups, {\r\n        type: r.type,\r\n        indexA: r.indexA,\r\n        indexB: r.indexB,\r\n        length: r.length,\r\n        isCollision: !bothFixed && collide ? 1 : 0\r\n      });\r\n    }\r\n  };\r\n\r\n  // Bending Horizontal\r\n  if (options.bendingHorizontal) {\r\n    const raw: RawConstraint[] = [];\r\n    const pairs = options.isLoop\r\n      ? Array.from({ length: n }, (_, i) => [i, (i + 2) % n])\r\n      : Array.from({ length: Math.max(0, n - 2) }, (_, i) => [i, i + 2]);\r\n    for (const [a, b] of pairs) {\r\n      createHorizontal(rootPoints[a], rootPoints[b], ConstraintType.Bending_Horizontal, raw);\r\n    }\r\n    addRaw(raw, false);\r\n  }\r\n\r\n  // Bending Vertical\r\n  if (options.bendingVertical) {\r\n    const raw: RawConstraint[] = [];\r\n    for (const root of rootPoints) {\r\n      createBendingVertical(root, raw);\r\n    }\r\n    addRaw(raw, false);\r\n  }\r\n\r\n  // Shear\r\n  if (options.shear) {\r\n    const raw: RawConstraint[] = [];\r\n    const pairs = options.isLoop\r\n      ? Array.from({ length: n }, (_, i) => [i, (i + 1) % n])\r\n      : Array.from({ length: Math.max(0, n - 1) }, (_, i) => [i, i + 1]);\r\n    for (const [a, b] of pairs) {\r\n      createShear(rootPoints[a], rootPoints[b], raw);\r\n    }\r\n    addRaw(raw, options.enableSurfaceCollision || options.collideShear);\r\n  }\r\n\r\n  // Structural Horizontal\r\n  if (options.structuralHorizontal) {\r\n    const raw: RawConstraint[] = [];\r\n    const pairs = options.isLoop\r\n      ? Array.from({ length: n }, (_, i) => [i, (i + 1) % n])\r\n      : Array.from({ length: Math.max(0, n - 1) }, (_, i) => [i, i + 1]);\r\n    for (const [a, b] of pairs) {\r\n      createHorizontal(rootPoints[a], rootPoints[b], ConstraintType.Structural_Horizontal, raw);\r\n    }\r\n    addRaw(raw, options.enableSurfaceCollision || options.collideStructuralHorizontal);\r\n  }\r\n\r\n  // Structural Vertical\r\n  if (options.structuralVertical) {\r\n    const raw: RawConstraint[] = [];\r\n    for (const root of rootPoints) {\r\n      createStructuralVertical(root, raw);\r\n    }\r\n    addRaw(raw, options.enableSurfaceCollision || options.collideStructuralVertical);\r\n  }\r\n\r\n  // Flatten groups into single array\r\n  return groups.flat();\r\n}\r\n\r\nexport function buildSurfaceFaces(rootPoints: BoneNode[], isLoop: boolean): number[] {\r\n  const out: number[] = [];\r\n  const n = rootPoints.length;\r\n  for (let i = 0; i < n - 1; i++) {\r\n    createSurfaceFaces(rootPoints[i], rootPoints[i + 1], out);\r\n  }\r\n  if (isLoop && n > 1) {\r\n    createSurfaceFaces(rootPoints[n - 1], rootPoints[0], out);\r\n  }\r\n  return out;\r\n}\r\n\r\nexport function computeMaxDepth(rootPoints: BoneNode[]): number {\r\n  let max = 0;\r\n  function walk(node: BoneNode) {\r\n    if (node.depth > max) {\r\n      max = node.depth;\r\n    }\r\n    for (const c of node.children) {\r\n      walk(c);\r\n    }\r\n  }\r\n  for (const r of rootPoints) {\r\n    walk(r);\r\n  }\r\n  return max;\r\n}\r\n\r\nexport function sortRootPointsByProximity(\r\n  roots: BoneNode[],\r\n  ignoreY: boolean,\r\n  fixedBeginEnd: boolean\r\n): BoneNode[] {\r\n  if (roots.length <= 2) {\r\n    return [...roots];\r\n  }\r\n  const sorted: BoneNode[] = [];\r\n  const remaining = [...roots];\r\n\r\n  if (fixedBeginEnd) {\r\n    sorted.push(remaining.shift()!);\r\n    const last = remaining.pop()!;\r\n    while (remaining.length > 0) {\r\n      const cur = sorted[sorted.length - 1];\r\n      let bestIdx = 0,\r\n        bestDist = Infinity;\r\n      for (let i = 0; i < remaining.length; i++) {\r\n        const d = distXYZ(cur.position, remaining[i].position, ignoreY);\r\n        if (d < bestDist) {\r\n          bestDist = d;\r\n          bestIdx = i;\r\n        }\r\n      }\r\n      sorted.push(remaining.splice(bestIdx, 1)[0]);\r\n    }\r\n    sorted.push(last);\r\n  } else {\r\n    sorted.push(remaining.shift()!);\r\n    while (remaining.length > 0) {\r\n      const cur = sorted[sorted.length - 1];\r\n      let bestIdx = 0,\r\n        bestDist = Infinity;\r\n      for (let i = 0; i < remaining.length; i++) {\r\n        const d = distXYZ(cur.position, remaining[i].position, ignoreY);\r\n        if (d < bestDist) {\r\n          bestDist = d;\r\n          bestIdx = i;\r\n        }\r\n      }\r\n      sorted.push(remaining.splice(bestIdx, 1)[0]);\r\n    }\r\n  }\r\n  return sorted;\r\n}\r\n\r\n// ── Helpers ──\r\n\r\nfunction distXYZ(a: Vector3, b: Vector3, ignoreY: boolean): number {\r\n  const dx = a.x - b.x,\r\n    dz = a.z - b.z;\r\n  const dy = ignoreY ? 0 : a.y - b.y;\r\n  return dx * dx + dy * dy + dz * dz;\r\n}\r\n\r\n// Walk all nodes to find if a given index is fixed\r\nfunction isBoneFixed(roots: BoneNode[], index: number): boolean {\r\n  function find(node: BoneNode): boolean {\r\n    if (node.index === index) {\r\n      return node.isFixed;\r\n    }\r\n    for (const c of node.children) {\r\n      const r = find(c);\r\n      if (r !== undefined) {\r\n        return r;\r\n      }\r\n    }\r\n    return false;\r\n  }\r\n  for (const r of roots) {\r\n    const res = find(r);\r\n    if (res) {\r\n      return true;\r\n    }\r\n  }\r\n  return false;\r\n}\r\n"],"names":["getFirstChild","node","children","length","constraintLength","a","b","Vector3","distance","position","createStructuralVertical","out","child","push","type","ConstraintType","Structural_Vertical","indexA","index","indexB","createHorizontal","childA","childB","createShear","cA","cB","cA2","cB2","cA3","cB3","target1","Shear","target2","createBendingVertical","Bending_Vertical","findSameIndex","group","c","g","pushToGroups","groups","createSurfaceFaces","useForSurfaceCollision","buildConstraints","rootPoints","options","n","addRaw","raws","collide","r","bothFixed","isBoneFixed","isCollision","bendingHorizontal","raw","pairs","isLoop","Array","from","_","i","Math","max","Bending_Horizontal","bendingVertical","root","shear","enableSurfaceCollision","collideShear","structuralHorizontal","Structural_Horizontal","collideStructuralHorizontal","structuralVertical","collideStructuralVertical","flat","buildSurfaceFaces","computeMaxDepth","walk","depth","sortRootPointsByProximity","roots","ignoreY","fixedBeginEnd","sorted","remaining","shift","last","pop","cur","bestIdx","bestDist","Infinity","d","distXYZ","splice","dx","x","dz","z","dy","y","find","isFixed","undefined","res"],"mappings":"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"}
+{"version":3,"file":"constraints.js","sources":["../../../src/animation/joint_dynamics/constraints.ts"],"sourcesContent":["// Constraint creation utilities — port of SPCRJointDynamicsController constraint building\r\n\r\nimport { Vector3 } from '@zephyr3d/base';\r\nimport { ConstraintType, type Constraint, type BoneNode } from './types';\r\n\r\n/**\r\n * Options for constraint generation from a bone hierarchy.\r\n *\r\n * @public\r\n */\r\nexport interface ConstraintBuildOptions {\r\n  /** Generate parent→child vertical constraints */\r\n  structuralVertical: boolean;\r\n  /** Generate same-depth horizontal constraints across chains */\r\n  structuralHorizontal: boolean;\r\n  /** Generate diagonal cross-bracing constraints */\r\n  shear: boolean;\r\n  /** Generate skip-one vertical bending constraints */\r\n  bendingVertical: boolean;\r\n  /** Generate skip-one horizontal bending constraints */\r\n  bendingHorizontal: boolean;\r\n  /** Connect last root point back to first (for cylindrical topology like skirts) */\r\n  isLoop: boolean;\r\n  /** Enable per-constraint collision detection on structural vertical pairs */\r\n  collideStructuralVertical: boolean;\r\n  /** Enable per-constraint collision detection on structural horizontal pairs */\r\n  collideStructuralHorizontal: boolean;\r\n  /** Enable per-constraint collision detection on shear pairs */\r\n  collideShear: boolean;\r\n  /** Enable surface/triangle collision (overrides per-type collision flags) */\r\n  enableSurfaceCollision: boolean;\r\n}\r\n\r\ninterface RawConstraint {\r\n  type: ConstraintType;\r\n  indexA: number;\r\n  indexB: number;\r\n  length: number;\r\n}\r\n\r\nfunction getFirstChild(node: BoneNode): BoneNode | null {\r\n  return node.children.length > 0 ? node.children[0] : null;\r\n}\r\n\r\nfunction constraintLength(a: BoneNode, b: BoneNode): number {\r\n  return Vector3.distance(a.position, b.position);\r\n}\r\n\r\n// ── Structural Vertical: parent→child chains ──\r\n\r\nfunction createStructuralVertical(node: BoneNode, out: RawConstraint[]) {\r\n  for (const child of node.children) {\r\n    out.push({\r\n      type: ConstraintType.Structural_Vertical,\r\n      indexA: node.index,\r\n      indexB: child.index,\r\n      length: constraintLength(node, child)\r\n    });\r\n    createStructuralVertical(child, out);\r\n  }\r\n}\r\n\r\n// ── Structural Horizontal: same-depth siblings across chains ──\r\n\r\nfunction createHorizontal(\r\n  a: BoneNode | null,\r\n  b: BoneNode | null,\r\n  type: ConstraintType,\r\n  out: RawConstraint[]\r\n) {\r\n  if (!a || !b || a === b) {\r\n    return;\r\n  }\r\n  const childA = getFirstChild(a);\r\n  const childB = getFirstChild(b);\r\n\r\n  if (childA && childB) {\r\n    out.push({\r\n      type,\r\n      indexA: childA.index,\r\n      indexB: childB.index,\r\n      length: constraintLength(childA, childB)\r\n    });\r\n    createHorizontal(childA, childB, type, out);\r\n  } else if (childA && !childB) {\r\n    out.push({\r\n      type,\r\n      indexA: childA.index,\r\n      indexB: b.index,\r\n      length: constraintLength(childA, b)\r\n    });\r\n  } else if (!childA && childB) {\r\n    out.push({\r\n      type,\r\n      indexA: a.index,\r\n      indexB: childB.index,\r\n      length: constraintLength(a, childB)\r\n    });\r\n  }\r\n}\r\n\r\n// ── Shear: diagonal cross-bracing ──\r\n\r\nfunction createShear(a: BoneNode | null, b: BoneNode | null, out: RawConstraint[]) {\r\n  if (!a || !b || a === b) {\r\n    return;\r\n  }\r\n  const cA = getFirstChild(a);\r\n  const cB = getFirstChild(b);\r\n  const cA2 = cA ? getFirstChild(cA) : null;\r\n  const cB2 = cB ? getFirstChild(cB) : null;\r\n  const cA3 = cA2 ? getFirstChild(cA2) : null;\r\n  const cB3 = cB2 ? getFirstChild(cB2) : null;\r\n\r\n  const target1 = cA ?? cA2 ?? cA3;\r\n  if (target1) {\r\n    out.push({\r\n      type: ConstraintType.Shear,\r\n      indexA: target1.index,\r\n      indexB: b.index,\r\n      length: constraintLength(target1, b)\r\n    });\r\n  }\r\n\r\n  const target2 = cB ?? cB2 ?? cB3;\r\n  if (target2) {\r\n    out.push({\r\n      type: ConstraintType.Shear,\r\n      indexA: a.index,\r\n      indexB: target2.index,\r\n      length: constraintLength(a, target2)\r\n    });\r\n  }\r\n\r\n  createShear(cA, cB, out);\r\n}\r\n\r\n// ── Bending Vertical: skip-one (grandparent→grandchild) ──\r\n\r\nfunction createBendingVertical(node: BoneNode, out: RawConstraint[]) {\r\n  if (node.children.length !== 1) {\r\n    return;\r\n  }\r\n  const childA = node.children[0];\r\n  if (childA.children.length !== 1) {\r\n    return;\r\n  }\r\n  const childB = childA.children[0];\r\n\r\n  out.push({\r\n    type: ConstraintType.Bending_Vertical,\r\n    indexA: node.index,\r\n    indexB: childB.index,\r\n    length: constraintLength(node, childB)\r\n  });\r\n  createBendingVertical(childA, out);\r\n}\r\n\r\n// ── Constraint grouping (no shared point indices per group) ──\r\n\r\nfunction findSameIndex(group: Constraint[], c: Constraint): boolean {\r\n  for (const g of group) {\r\n    if (g.indexA === c.indexA || g.indexA === c.indexB || g.indexB === c.indexA || g.indexB === c.indexB) {\r\n      return true;\r\n    }\r\n  }\r\n  return false;\r\n}\r\n\r\nfunction pushToGroups(groups: Constraint[][], c: Constraint) {\r\n  for (const g of groups) {\r\n    if (!findSameIndex(g, c)) {\r\n      g.push(c);\r\n      return;\r\n    }\r\n  }\r\n  groups.push([c]);\r\n}\r\n\r\n// ── Surface faces (quads → 2 triangles of 3 indices) ──\r\n\r\nfunction createSurfaceFaces(a: BoneNode | null, b: BoneNode | null, out: number[]) {\r\n  if (!a || !b || a === b) {\r\n    return;\r\n  }\r\n  const cA = getFirstChild(a);\r\n  const cB = getFirstChild(b);\r\n  if (cA && cB) {\r\n    if (\r\n      a.useForSurfaceCollision !== false &&\r\n      b.useForSurfaceCollision !== false &&\r\n      cA.useForSurfaceCollision !== false &&\r\n      cB.useForSurfaceCollision !== false\r\n    ) {\r\n      // Quad ABCD → triangles ABC, CDA\r\n      out.push(a.index, b.index, cB.index, cB.index, cA.index, a.index);\r\n    }\r\n    createSurfaceFaces(cA, cB, out);\r\n  }\r\n}\r\n\r\n// ── Public API ──\r\n\r\n/**\r\n * Builds solver constraints from the supplied root chains.\r\n *\r\n * @public\r\n */\r\nexport function buildConstraints(rootPoints: BoneNode[], options: ConstraintBuildOptions): Constraint[] {\r\n  const n = rootPoints.length;\r\n  const groups: Constraint[][] = [];\r\n\r\n  const addRaw = (raws: RawConstraint[], collide: boolean) => {\r\n    for (const r of raws) {\r\n      const bothFixed = isBoneFixed(rootPoints, r.indexA) && isBoneFixed(rootPoints, r.indexB);\r\n      pushToGroups(groups, {\r\n        type: r.type,\r\n        indexA: r.indexA,\r\n        indexB: r.indexB,\r\n        length: r.length,\r\n        isCollision: !bothFixed && collide ? 1 : 0\r\n      });\r\n    }\r\n  };\r\n\r\n  // Bending Horizontal\r\n  if (options.bendingHorizontal) {\r\n    const raw: RawConstraint[] = [];\r\n    const pairs = options.isLoop\r\n      ? Array.from({ length: n }, (_, i) => [i, (i + 2) % n])\r\n      : Array.from({ length: Math.max(0, n - 2) }, (_, i) => [i, i + 2]);\r\n    for (const [a, b] of pairs) {\r\n      createHorizontal(rootPoints[a], rootPoints[b], ConstraintType.Bending_Horizontal, raw);\r\n    }\r\n    addRaw(raw, false);\r\n  }\r\n\r\n  // Bending Vertical\r\n  if (options.bendingVertical) {\r\n    const raw: RawConstraint[] = [];\r\n    for (const root of rootPoints) {\r\n      createBendingVertical(root, raw);\r\n    }\r\n    addRaw(raw, false);\r\n  }\r\n\r\n  // Shear\r\n  if (options.shear) {\r\n    const raw: RawConstraint[] = [];\r\n    const pairs = options.isLoop\r\n      ? Array.from({ length: n }, (_, i) => [i, (i + 1) % n])\r\n      : Array.from({ length: Math.max(0, n - 1) }, (_, i) => [i, i + 1]);\r\n    for (const [a, b] of pairs) {\r\n      createShear(rootPoints[a], rootPoints[b], raw);\r\n    }\r\n    addRaw(raw, options.enableSurfaceCollision || options.collideShear);\r\n  }\r\n\r\n  // Structural Horizontal\r\n  if (options.structuralHorizontal) {\r\n    const raw: RawConstraint[] = [];\r\n    const pairs = options.isLoop\r\n      ? Array.from({ length: n }, (_, i) => [i, (i + 1) % n])\r\n      : Array.from({ length: Math.max(0, n - 1) }, (_, i) => [i, i + 1]);\r\n    for (const [a, b] of pairs) {\r\n      createHorizontal(rootPoints[a], rootPoints[b], ConstraintType.Structural_Horizontal, raw);\r\n    }\r\n    addRaw(raw, options.enableSurfaceCollision || options.collideStructuralHorizontal);\r\n  }\r\n\r\n  // Structural Vertical\r\n  if (options.structuralVertical) {\r\n    const raw: RawConstraint[] = [];\r\n    for (const root of rootPoints) {\r\n      createStructuralVertical(root, raw);\r\n    }\r\n    addRaw(raw, options.enableSurfaceCollision || options.collideStructuralVertical);\r\n  }\r\n\r\n  // Flatten groups into single array\r\n  return groups.flat();\r\n}\r\n\r\n/**\r\n * Builds triangle indices used for surface collision.\r\n *\r\n * @public\r\n */\r\nexport function buildSurfaceFaces(rootPoints: BoneNode[], isLoop: boolean): number[] {\r\n  const out: number[] = [];\r\n  const n = rootPoints.length;\r\n  for (let i = 0; i < n - 1; i++) {\r\n    createSurfaceFaces(rootPoints[i], rootPoints[i + 1], out);\r\n  }\r\n  if (isLoop && n > 1) {\r\n    createSurfaceFaces(rootPoints[n - 1], rootPoints[0], out);\r\n  }\r\n  return out;\r\n}\r\n\r\n/**\r\n * Computes the maximum chain depth among all root points.\r\n *\r\n * @public\r\n */\r\nexport function computeMaxDepth(rootPoints: BoneNode[]): number {\r\n  let max = 0;\r\n  function walk(node: BoneNode) {\r\n    if (node.depth > max) {\r\n      max = node.depth;\r\n    }\r\n    for (const c of node.children) {\r\n      walk(c);\r\n    }\r\n  }\r\n  for (const r of rootPoints) {\r\n    walk(r);\r\n  }\r\n  return max;\r\n}\r\n\r\n/**\r\n * Sorts root points by proximity to the supplied reference position.\r\n *\r\n * @public\r\n */\r\nexport function sortRootPointsByProximity(\r\n  roots: BoneNode[],\r\n  ignoreY: boolean,\r\n  fixedBeginEnd: boolean\r\n): BoneNode[] {\r\n  if (roots.length <= 2) {\r\n    return [...roots];\r\n  }\r\n  const sorted: BoneNode[] = [];\r\n  const remaining = [...roots];\r\n\r\n  if (fixedBeginEnd) {\r\n    sorted.push(remaining.shift()!);\r\n    const last = remaining.pop()!;\r\n    while (remaining.length > 0) {\r\n      const cur = sorted[sorted.length - 1];\r\n      let bestIdx = 0,\r\n        bestDist = Infinity;\r\n      for (let i = 0; i < remaining.length; i++) {\r\n        const d = distXYZ(cur.position, remaining[i].position, ignoreY);\r\n        if (d < bestDist) {\r\n          bestDist = d;\r\n          bestIdx = i;\r\n        }\r\n      }\r\n      sorted.push(remaining.splice(bestIdx, 1)[0]);\r\n    }\r\n    sorted.push(last);\r\n  } else {\r\n    sorted.push(remaining.shift()!);\r\n    while (remaining.length > 0) {\r\n      const cur = sorted[sorted.length - 1];\r\n      let bestIdx = 0,\r\n        bestDist = Infinity;\r\n      for (let i = 0; i < remaining.length; i++) {\r\n        const d = distXYZ(cur.position, remaining[i].position, ignoreY);\r\n        if (d < bestDist) {\r\n          bestDist = d;\r\n          bestIdx = i;\r\n        }\r\n      }\r\n      sorted.push(remaining.splice(bestIdx, 1)[0]);\r\n    }\r\n  }\r\n  return sorted;\r\n}\r\n\r\n// ── Helpers ──\r\n\r\nfunction distXYZ(a: Vector3, b: Vector3, ignoreY: boolean): number {\r\n  const dx = a.x - b.x,\r\n    dz = a.z - b.z;\r\n  const dy = ignoreY ? 0 : a.y - b.y;\r\n  return dx * dx + dy * dy + dz * dz;\r\n}\r\n\r\n// Walk all nodes to find if a given index is fixed\r\nfunction isBoneFixed(roots: BoneNode[], index: number): boolean {\r\n  function find(node: BoneNode): boolean {\r\n    if (node.index === index) {\r\n      return node.isFixed;\r\n    }\r\n    for (const c of node.children) {\r\n      const r = find(c);\r\n      if (r !== undefined) {\r\n        return r;\r\n      }\r\n    }\r\n    return false;\r\n  }\r\n  for (const r of roots) {\r\n    const res = find(r);\r\n    if (res) {\r\n      return true;\r\n    }\r\n  }\r\n  return false;\r\n}\r\n"],"names":["getFirstChild","node","children","length","constraintLength","a","b","Vector3","distance","position","createStructuralVertical","out","child","push","type","ConstraintType","Structural_Vertical","indexA","index","indexB","createHorizontal","childA","childB","createShear","cA","cB","cA2","cB2","cA3","cB3","target1","Shear","target2","createBendingVertical","Bending_Vertical","findSameIndex","group","c","g","pushToGroups","groups","createSurfaceFaces","useForSurfaceCollision","buildConstraints","rootPoints","options","n","addRaw","raws","collide","r","bothFixed","isBoneFixed","isCollision","bendingHorizontal","raw","pairs","isLoop","Array","from","_","i","Math","max","Bending_Horizontal","bendingVertical","root","shear","enableSurfaceCollision","collideShear","structuralHorizontal","Structural_Horizontal","collideStructuralHorizontal","structuralVertical","collideStructuralVertical","flat","buildSurfaceFaces","computeMaxDepth","walk","depth","sortRootPointsByProximity","roots","ignoreY","fixedBeginEnd","sorted","remaining","shift","last","pop","cur","bestIdx","bestDist","Infinity","d","distXYZ","splice","dx","x","dz","z","dy","y","find","isFixed","undefined","res"],"mappings":";;;AAAA;AAwCA,SAASA,cAAcC,IAAc,EAAA;IACnC,OAAOA,IAAAA,CAAKC,QAAQ,CAACC,MAAM,GAAG,IAAIF,IAAKC,CAAAA,QAAQ,CAAC,CAAA,CAAE,GAAG,IAAA;AACvD;AAEA,SAASE,gBAAAA,CAAiBC,CAAW,EAAEC,CAAW,EAAA;AAChD,IAAA,OAAOC,QAAQC,QAAQ,CAACH,EAAEI,QAAQ,EAAEH,EAAEG,QAAQ,CAAA;AAChD;AAEA;AAEA,SAASC,wBAAAA,CAAyBT,IAAc,EAAEU,GAAoB,EAAA;AACpE,IAAA,KAAK,MAAMC,KAAAA,IAASX,IAAKC,CAAAA,QAAQ,CAAE;AACjCS,QAAAA,GAAAA,CAAIE,IAAI,CAAC;AACPC,YAAAA,IAAAA,EAAMC,eAAeC,mBAAmB;AACxCC,YAAAA,MAAAA,EAAQhB,KAAKiB,KAAK;AAClBC,YAAAA,MAAAA,EAAQP,MAAMM,KAAK;AACnBf,YAAAA,MAAAA,EAAQC,iBAAiBH,IAAMW,EAAAA,KAAAA;AACjC,SAAA,CAAA;AACAF,QAAAA,wBAAAA,CAAyBE,KAAOD,EAAAA,GAAAA,CAAAA;AAClC;AACF;AAEA;AAEA,SAASS,iBACPf,CAAkB,EAClBC,CAAkB,EAClBQ,IAAoB,EACpBH,GAAoB,EAAA;AAEpB,IAAA,IAAI,CAACN,CAAAA,IAAK,CAACC,CAAAA,IAAKD,MAAMC,CAAG,EAAA;AACvB,QAAA;AACF;AACA,IAAA,MAAMe,SAASrB,aAAcK,CAAAA,CAAAA,CAAAA;AAC7B,IAAA,MAAMiB,SAAStB,aAAcM,CAAAA,CAAAA,CAAAA;AAE7B,IAAA,IAAIe,UAAUC,MAAQ,EAAA;AACpBX,QAAAA,GAAAA,CAAIE,IAAI,CAAC;AACPC,YAAAA,IAAAA;AACAG,YAAAA,MAAAA,EAAQI,OAAOH,KAAK;AACpBC,YAAAA,MAAAA,EAAQG,OAAOJ,KAAK;AACpBf,YAAAA,MAAAA,EAAQC,iBAAiBiB,MAAQC,EAAAA,MAAAA;AACnC,SAAA,CAAA;QACAF,gBAAiBC,CAAAA,MAAAA,EAAQC,QAAQR,IAAMH,EAAAA,GAAAA,CAAAA;KAClC,MAAA,IAAIU,MAAU,IAAA,CAACC,MAAQ,EAAA;AAC5BX,QAAAA,GAAAA,CAAIE,IAAI,CAAC;AACPC,YAAAA,IAAAA;AACAG,YAAAA,MAAAA,EAAQI,OAAOH,KAAK;AACpBC,YAAAA,MAAAA,EAAQb,EAAEY,KAAK;AACff,YAAAA,MAAAA,EAAQC,iBAAiBiB,MAAQf,EAAAA,CAAAA;AACnC,SAAA,CAAA;KACK,MAAA,IAAI,CAACe,MAAAA,IAAUC,MAAQ,EAAA;AAC5BX,QAAAA,GAAAA,CAAIE,IAAI,CAAC;AACPC,YAAAA,IAAAA;AACAG,YAAAA,MAAAA,EAAQZ,EAAEa,KAAK;AACfC,YAAAA,MAAAA,EAAQG,OAAOJ,KAAK;AACpBf,YAAAA,MAAAA,EAAQC,iBAAiBC,CAAGiB,EAAAA,MAAAA;AAC9B,SAAA,CAAA;AACF;AACF;AAEA;AAEA,SAASC,WAAYlB,CAAAA,CAAkB,EAAEC,CAAkB,EAAEK,GAAoB,EAAA;AAC/E,IAAA,IAAI,CAACN,CAAAA,IAAK,CAACC,CAAAA,IAAKD,MAAMC,CAAG,EAAA;AACvB,QAAA;AACF;AACA,IAAA,MAAMkB,KAAKxB,aAAcK,CAAAA,CAAAA,CAAAA;AACzB,IAAA,MAAMoB,KAAKzB,aAAcM,CAAAA,CAAAA,CAAAA;IACzB,MAAMoB,GAAAA,GAAMF,EAAKxB,GAAAA,aAAAA,CAAcwB,EAAM,CAAA,GAAA,IAAA;IACrC,MAAMG,GAAAA,GAAMF,EAAKzB,GAAAA,aAAAA,CAAcyB,EAAM,CAAA,GAAA,IAAA;IACrC,MAAMG,GAAAA,GAAMF,GAAM1B,GAAAA,aAAAA,CAAc0B,GAAO,CAAA,GAAA,IAAA;IACvC,MAAMG,GAAAA,GAAMF,GAAM3B,GAAAA,aAAAA,CAAc2B,GAAO,CAAA,GAAA,IAAA;IAEvC,MAAMG,OAAAA,GAAUN,MAAME,GAAOE,IAAAA,GAAAA;AAC7B,IAAA,IAAIE,OAAS,EAAA;AACXnB,QAAAA,GAAAA,CAAIE,IAAI,CAAC;AACPC,YAAAA,IAAAA,EAAMC,eAAegB,KAAK;AAC1Bd,YAAAA,MAAAA,EAAQa,QAAQZ,KAAK;AACrBC,YAAAA,MAAAA,EAAQb,EAAEY,KAAK;AACff,YAAAA,MAAAA,EAAQC,iBAAiB0B,OAASxB,EAAAA,CAAAA;AACpC,SAAA,CAAA;AACF;IAEA,MAAM0B,OAAAA,GAAUP,MAAME,GAAOE,IAAAA,GAAAA;AAC7B,IAAA,IAAIG,OAAS,EAAA;AACXrB,QAAAA,GAAAA,CAAIE,IAAI,CAAC;AACPC,YAAAA,IAAAA,EAAMC,eAAegB,KAAK;AAC1Bd,YAAAA,MAAAA,EAAQZ,EAAEa,KAAK;AACfC,YAAAA,MAAAA,EAAQa,QAAQd,KAAK;AACrBf,YAAAA,MAAAA,EAAQC,iBAAiBC,CAAG2B,EAAAA,OAAAA;AAC9B,SAAA,CAAA;AACF;AAEAT,IAAAA,WAAAA,CAAYC,IAAIC,EAAId,EAAAA,GAAAA,CAAAA;AACtB;AAEA;AAEA,SAASsB,qBAAAA,CAAsBhC,IAAc,EAAEU,GAAoB,EAAA;AACjE,IAAA,IAAIV,IAAKC,CAAAA,QAAQ,CAACC,MAAM,KAAK,CAAG,EAAA;AAC9B,QAAA;AACF;AACA,IAAA,MAAMkB,MAASpB,GAAAA,IAAAA,CAAKC,QAAQ,CAAC,CAAE,CAAA;AAC/B,IAAA,IAAImB,MAAOnB,CAAAA,QAAQ,CAACC,MAAM,KAAK,CAAG,EAAA;AAChC,QAAA;AACF;AACA,IAAA,MAAMmB,MAASD,GAAAA,MAAAA,CAAOnB,QAAQ,CAAC,CAAE,CAAA;AAEjCS,IAAAA,GAAAA,CAAIE,IAAI,CAAC;AACPC,QAAAA,IAAAA,EAAMC,eAAemB,gBAAgB;AACrCjB,QAAAA,MAAAA,EAAQhB,KAAKiB,KAAK;AAClBC,QAAAA,MAAAA,EAAQG,OAAOJ,KAAK;AACpBf,QAAAA,MAAAA,EAAQC,iBAAiBH,IAAMqB,EAAAA,MAAAA;AACjC,KAAA,CAAA;AACAW,IAAAA,qBAAAA,CAAsBZ,MAAQV,EAAAA,GAAAA,CAAAA;AAChC;AAEA;AAEA,SAASwB,aAAAA,CAAcC,KAAmB,EAAEC,CAAa,EAAA;IACvD,KAAK,MAAMC,KAAKF,KAAO,CAAA;QACrB,IAAIE,CAAAA,CAAErB,MAAM,KAAKoB,CAAAA,CAAEpB,MAAM,IAAIqB,CAAAA,CAAErB,MAAM,KAAKoB,CAAElB,CAAAA,MAAM,IAAImB,CAAEnB,CAAAA,MAAM,KAAKkB,CAAAA,CAAEpB,MAAM,IAAIqB,EAAEnB,MAAM,KAAKkB,CAAElB,CAAAA,MAAM,EAAE;YACpG,OAAO,IAAA;AACT;AACF;IACA,OAAO,KAAA;AACT;AAEA,SAASoB,YAAAA,CAAaC,MAAsB,EAAEH,CAAa,EAAA;IACzD,KAAK,MAAMC,KAAKE,MAAQ,CAAA;QACtB,IAAI,CAACL,aAAcG,CAAAA,CAAAA,EAAGD,CAAI,CAAA,EAAA;AACxBC,YAAAA,CAAAA,CAAEzB,IAAI,CAACwB,CAAAA,CAAAA;AACP,YAAA;AACF;AACF;AACAG,IAAAA,MAAAA,CAAO3B,IAAI,CAAC;AAACwB,QAAAA;AAAE,KAAA,CAAA;AACjB;AAEA;AAEA,SAASI,kBAAmBpC,CAAAA,CAAkB,EAAEC,CAAkB,EAAEK,GAAa,EAAA;AAC/E,IAAA,IAAI,CAACN,CAAAA,IAAK,CAACC,CAAAA,IAAKD,MAAMC,CAAG,EAAA;AACvB,QAAA;AACF;AACA,IAAA,MAAMkB,KAAKxB,aAAcK,CAAAA,CAAAA,CAAAA;AACzB,IAAA,MAAMoB,KAAKzB,aAAcM,CAAAA,CAAAA,CAAAA;AACzB,IAAA,IAAIkB,MAAMC,EAAI,EAAA;AACZ,QAAA,IACEpB,CAAEqC,CAAAA,sBAAsB,KAAK,KAAA,IAC7BpC,EAAEoC,sBAAsB,KAAK,KAC7BlB,IAAAA,EAAAA,CAAGkB,sBAAsB,KAAK,KAAA,IAC9BjB,EAAGiB,CAAAA,sBAAsB,KAAK,KAC9B,EAAA;;AAEA/B,YAAAA,GAAAA,CAAIE,IAAI,CAACR,CAAAA,CAAEa,KAAK,EAAEZ,CAAAA,CAAEY,KAAK,EAAEO,EAAAA,CAAGP,KAAK,EAAEO,GAAGP,KAAK,EAAEM,GAAGN,KAAK,EAAEb,EAAEa,KAAK,CAAA;AAClE;AACAuB,QAAAA,kBAAAA,CAAmBjB,IAAIC,EAAId,EAAAA,GAAAA,CAAAA;AAC7B;AACF;AAEA;AAEA;;;;AAIC,IACM,SAASgC,gBAAiBC,CAAAA,UAAsB,EAAEC,OAA+B,EAAA;IACtF,MAAMC,CAAAA,GAAIF,WAAWzC,MAAM;AAC3B,IAAA,MAAMqC,SAAyB,EAAE;IAEjC,MAAMO,MAAAA,GAAS,CAACC,IAAuBC,EAAAA,OAAAA,GAAAA;QACrC,KAAK,MAAMC,KAAKF,IAAM,CAAA;YACpB,MAAMG,SAAAA,GAAYC,YAAYR,UAAYM,EAAAA,CAAAA,CAAEjC,MAAM,CAAKmC,IAAAA,WAAAA,CAAYR,UAAYM,EAAAA,CAAAA,CAAE/B,MAAM,CAAA;AACvFoB,YAAAA,YAAAA,CAAaC,MAAQ,EAAA;AACnB1B,gBAAAA,IAAAA,EAAMoC,EAAEpC,IAAI;AACZG,gBAAAA,MAAAA,EAAQiC,EAAEjC,MAAM;AAChBE,gBAAAA,MAAAA,EAAQ+B,EAAE/B,MAAM;AAChBhB,gBAAAA,MAAAA,EAAQ+C,EAAE/C,MAAM;gBAChBkD,WAAa,EAAA,CAACF,SAAaF,IAAAA,OAAAA,GAAU,CAAI,GAAA;AAC3C,aAAA,CAAA;AACF;AACF,KAAA;;IAGA,IAAIJ,OAAAA,CAAQS,iBAAiB,EAAE;AAC7B,QAAA,MAAMC,MAAuB,EAAE;AAC/B,QAAA,MAAMC,QAAQX,OAAQY,CAAAA,MAAM,GACxBC,KAAAA,CAAMC,IAAI,CAAC;YAAExD,MAAQ2C,EAAAA;SAAK,EAAA,CAACc,GAAGC,CAAM,GAAA;AAACA,gBAAAA,CAAAA;gBAAIA,CAAAA,CAAAA,GAAI,CAAA,IAAKf;aAAE,CACpDY,GAAAA,KAAAA,CAAMC,IAAI,CAAC;AAAExD,YAAAA,MAAAA,EAAQ2D,IAAKC,CAAAA,GAAG,CAAC,CAAA,EAAGjB,CAAI,GAAA,CAAA;SAAM,EAAA,CAACc,GAAGC,CAAM,GAAA;AAACA,gBAAAA,CAAAA;gBAAGA,CAAI,GAAA;AAAE,aAAA,CAAA;AACnE,QAAA,KAAK,MAAM,CAACxD,CAAGC,EAAAA,CAAAA,CAAE,IAAIkD,KAAO,CAAA;YAC1BpC,gBAAiBwB,CAAAA,UAAU,CAACvC,CAAAA,CAAE,EAAEuC,UAAU,CAACtC,CAAE,CAAA,EAAES,cAAeiD,CAAAA,kBAAkB,EAAET,GAAAA,CAAAA;AACpF;AACAR,QAAAA,MAAAA,CAAOQ,GAAK,EAAA,KAAA,CAAA;AACd;;IAGA,IAAIV,OAAAA,CAAQoB,eAAe,EAAE;AAC3B,QAAA,MAAMV,MAAuB,EAAE;QAC/B,KAAK,MAAMW,QAAQtB,UAAY,CAAA;AAC7BX,YAAAA,qBAAAA,CAAsBiC,IAAMX,EAAAA,GAAAA,CAAAA;AAC9B;AACAR,QAAAA,MAAAA,CAAOQ,GAAK,EAAA,KAAA,CAAA;AACd;;IAGA,IAAIV,OAAAA,CAAQsB,KAAK,EAAE;AACjB,QAAA,MAAMZ,MAAuB,EAAE;AAC/B,QAAA,MAAMC,QAAQX,OAAQY,CAAAA,MAAM,GACxBC,KAAAA,CAAMC,IAAI,CAAC;YAAExD,MAAQ2C,EAAAA;SAAK,EAAA,CAACc,GAAGC,CAAM,GAAA;AAACA,gBAAAA,CAAAA;gBAAIA,CAAAA,CAAAA,GAAI,CAAA,IAAKf;aAAE,CACpDY,GAAAA,KAAAA,CAAMC,IAAI,CAAC;AAAExD,YAAAA,MAAAA,EAAQ2D,IAAKC,CAAAA,GAAG,CAAC,CAAA,EAAGjB,CAAI,GAAA,CAAA;SAAM,EAAA,CAACc,GAAGC,CAAM,GAAA;AAACA,gBAAAA,CAAAA;gBAAGA,CAAI,GAAA;AAAE,aAAA,CAAA;AACnE,QAAA,KAAK,MAAM,CAACxD,CAAGC,EAAAA,CAAAA,CAAE,IAAIkD,KAAO,CAAA;AAC1BjC,YAAAA,WAAAA,CAAYqB,UAAU,CAACvC,CAAAA,CAAE,EAAEuC,UAAU,CAACtC,EAAE,EAAEiD,GAAAA,CAAAA;AAC5C;AACAR,QAAAA,MAAAA,CAAOQ,GAAKV,EAAAA,OAAAA,CAAQuB,sBAAsB,IAAIvB,QAAQwB,YAAY,CAAA;AACpE;;IAGA,IAAIxB,OAAAA,CAAQyB,oBAAoB,EAAE;AAChC,QAAA,MAAMf,MAAuB,EAAE;AAC/B,QAAA,MAAMC,QAAQX,OAAQY,CAAAA,MAAM,GACxBC,KAAAA,CAAMC,IAAI,CAAC;YAAExD,MAAQ2C,EAAAA;SAAK,EAAA,CAACc,GAAGC,CAAM,GAAA;AAACA,gBAAAA,CAAAA;gBAAIA,CAAAA,CAAAA,GAAI,CAAA,IAAKf;aAAE,CACpDY,GAAAA,KAAAA,CAAMC,IAAI,CAAC;AAAExD,YAAAA,MAAAA,EAAQ2D,IAAKC,CAAAA,GAAG,CAAC,CAAA,EAAGjB,CAAI,GAAA,CAAA;SAAM,EAAA,CAACc,GAAGC,CAAM,GAAA;AAACA,gBAAAA,CAAAA;gBAAGA,CAAI,GAAA;AAAE,aAAA,CAAA;AACnE,QAAA,KAAK,MAAM,CAACxD,CAAGC,EAAAA,CAAAA,CAAE,IAAIkD,KAAO,CAAA;YAC1BpC,gBAAiBwB,CAAAA,UAAU,CAACvC,CAAAA,CAAE,EAAEuC,UAAU,CAACtC,CAAE,CAAA,EAAES,cAAewD,CAAAA,qBAAqB,EAAEhB,GAAAA,CAAAA;AACvF;AACAR,QAAAA,MAAAA,CAAOQ,GAAKV,EAAAA,OAAAA,CAAQuB,sBAAsB,IAAIvB,QAAQ2B,2BAA2B,CAAA;AACnF;;IAGA,IAAI3B,OAAAA,CAAQ4B,kBAAkB,EAAE;AAC9B,QAAA,MAAMlB,MAAuB,EAAE;QAC/B,KAAK,MAAMW,QAAQtB,UAAY,CAAA;AAC7BlC,YAAAA,wBAAAA,CAAyBwD,IAAMX,EAAAA,GAAAA,CAAAA;AACjC;AACAR,QAAAA,MAAAA,CAAOQ,GAAKV,EAAAA,OAAAA,CAAQuB,sBAAsB,IAAIvB,QAAQ6B,yBAAyB,CAAA;AACjF;;AAGA,IAAA,OAAOlC,OAAOmC,IAAI,EAAA;AACpB;AAEA;;;;AAIC,IACM,SAASC,iBAAkBhC,CAAAA,UAAsB,EAAEa,MAAe,EAAA;AACvE,IAAA,MAAM9C,MAAgB,EAAE;IACxB,MAAMmC,CAAAA,GAAIF,WAAWzC,MAAM;AAC3B,IAAA,IAAK,IAAI0D,CAAI,GAAA,CAAA,EAAGA,CAAIf,GAAAA,CAAAA,GAAI,GAAGe,CAAK,EAAA,CAAA;QAC9BpB,kBAAmBG,CAAAA,UAAU,CAACiB,CAAE,CAAA,EAAEjB,UAAU,CAACiB,CAAAA,GAAI,EAAE,EAAElD,GAAAA,CAAAA;AACvD;IACA,IAAI8C,MAAAA,IAAUX,IAAI,CAAG,EAAA;QACnBL,kBAAmBG,CAAAA,UAAU,CAACE,CAAI,GAAA,CAAA,CAAE,EAAEF,UAAU,CAAC,EAAE,EAAEjC,GAAAA,CAAAA;AACvD;IACA,OAAOA,GAAAA;AACT;AAEA;;;;IAKO,SAASkE,eAAAA,CAAgBjC,UAAsB,EAAA;AACpD,IAAA,IAAImB,GAAM,GAAA,CAAA;AACV,IAAA,SAASe,KAAK7E,IAAc,EAAA;QAC1B,IAAIA,IAAAA,CAAK8E,KAAK,GAAGhB,GAAK,EAAA;AACpBA,YAAAA,GAAAA,GAAM9D,KAAK8E,KAAK;AAClB;AACA,QAAA,KAAK,MAAM1C,CAAAA,IAAKpC,IAAKC,CAAAA,QAAQ,CAAE;YAC7B4E,IAAKzC,CAAAA,CAAAA,CAAAA;AACP;AACF;IACA,KAAK,MAAMa,KAAKN,UAAY,CAAA;QAC1BkC,IAAK5B,CAAAA,CAAAA,CAAAA;AACP;IACA,OAAOa,GAAAA;AACT;AAEA;;;;AAIC,IACM,SAASiB,yBAAAA,CACdC,KAAiB,EACjBC,OAAgB,EAChBC,aAAsB,EAAA;IAEtB,IAAIF,KAAAA,CAAM9E,MAAM,IAAI,CAAG,EAAA;QACrB,OAAO;AAAI8E,YAAAA,GAAAA;AAAM,SAAA;AACnB;AACA,IAAA,MAAMG,SAAqB,EAAE;AAC7B,IAAA,MAAMC,SAAY,GAAA;AAAIJ,QAAAA,GAAAA;AAAM,KAAA;AAE5B,IAAA,IAAIE,aAAe,EAAA;QACjBC,MAAOvE,CAAAA,IAAI,CAACwE,SAAAA,CAAUC,KAAK,EAAA,CAAA;QAC3B,MAAMC,IAAAA,GAAOF,UAAUG,GAAG,EAAA;QAC1B,MAAOH,SAAAA,CAAUlF,MAAM,GAAG,CAAG,CAAA;AAC3B,YAAA,MAAMsF,MAAML,MAAM,CAACA,MAAOjF,CAAAA,MAAM,GAAG,CAAE,CAAA;YACrC,IAAIuF,OAAAA,GAAU,GACZC,QAAWC,GAAAA,QAAAA;AACb,YAAA,IAAK,IAAI/B,CAAI,GAAA,CAAA,EAAGA,IAAIwB,SAAUlF,CAAAA,MAAM,EAAE0D,CAAK,EAAA,CAAA;gBACzC,MAAMgC,CAAAA,GAAIC,OAAQL,CAAAA,GAAAA,CAAIhF,QAAQ,EAAE4E,SAAS,CAACxB,CAAAA,CAAE,CAACpD,QAAQ,EAAEyE,OAAAA,CAAAA;AACvD,gBAAA,IAAIW,IAAIF,QAAU,EAAA;oBAChBA,QAAWE,GAAAA,CAAAA;oBACXH,OAAU7B,GAAAA,CAAAA;AACZ;AACF;YACAuB,MAAOvE,CAAAA,IAAI,CAACwE,SAAUU,CAAAA,MAAM,CAACL,OAAS,EAAA,CAAA,CAAE,CAAC,CAAE,CAAA,CAAA;AAC7C;AACAN,QAAAA,MAAAA,CAAOvE,IAAI,CAAC0E,IAAAA,CAAAA;KACP,MAAA;QACLH,MAAOvE,CAAAA,IAAI,CAACwE,SAAAA,CAAUC,KAAK,EAAA,CAAA;QAC3B,MAAOD,SAAAA,CAAUlF,MAAM,GAAG,CAAG,CAAA;AAC3B,YAAA,MAAMsF,MAAML,MAAM,CAACA,MAAOjF,CAAAA,MAAM,GAAG,CAAE,CAAA;YACrC,IAAIuF,OAAAA,GAAU,GACZC,QAAWC,GAAAA,QAAAA;AACb,YAAA,IAAK,IAAI/B,CAAI,GAAA,CAAA,EAAGA,IAAIwB,SAAUlF,CAAAA,MAAM,EAAE0D,CAAK,EAAA,CAAA;gBACzC,MAAMgC,CAAAA,GAAIC,OAAQL,CAAAA,GAAAA,CAAIhF,QAAQ,EAAE4E,SAAS,CAACxB,CAAAA,CAAE,CAACpD,QAAQ,EAAEyE,OAAAA,CAAAA;AACvD,gBAAA,IAAIW,IAAIF,QAAU,EAAA;oBAChBA,QAAWE,GAAAA,CAAAA;oBACXH,OAAU7B,GAAAA,CAAAA;AACZ;AACF;YACAuB,MAAOvE,CAAAA,IAAI,CAACwE,SAAUU,CAAAA,MAAM,CAACL,OAAS,EAAA,CAAA,CAAE,CAAC,CAAE,CAAA,CAAA;AAC7C;AACF;IACA,OAAON,MAAAA;AACT;AAEA;AAEA,SAASU,OAAQzF,CAAAA,CAAU,EAAEC,CAAU,EAAE4E,OAAgB,EAAA;AACvD,IAAA,MAAMc,EAAK3F,GAAAA,CAAAA,CAAE4F,CAAC,GAAG3F,CAAE2F,CAAAA,CAAC,EAClBC,EAAAA,GAAK7F,CAAE8F,CAAAA,CAAC,GAAG7F,CAAAA,CAAE6F,CAAC;AAChB,IAAA,MAAMC,KAAKlB,OAAU,GAAA,CAAA,GAAI7E,EAAEgG,CAAC,GAAG/F,EAAE+F,CAAC;AAClC,IAAA,OAAOL,EAAKA,GAAAA,EAAAA,GAAKI,EAAKA,GAAAA,EAAAA,GAAKF,EAAKA,GAAAA,EAAAA;AAClC;AAEA;AACA,SAAS9C,WAAAA,CAAY6B,KAAiB,EAAE/D,KAAa,EAAA;AACnD,IAAA,SAASoF,KAAKrG,IAAc,EAAA;QAC1B,IAAIA,IAAAA,CAAKiB,KAAK,KAAKA,KAAO,EAAA;AACxB,YAAA,OAAOjB,KAAKsG,OAAO;AACrB;AACA,QAAA,KAAK,MAAMlE,CAAAA,IAAKpC,IAAKC,CAAAA,QAAQ,CAAE;AAC7B,YAAA,MAAMgD,IAAIoD,IAAKjE,CAAAA,CAAAA,CAAAA;AACf,YAAA,IAAIa,MAAMsD,SAAW,EAAA;gBACnB,OAAOtD,CAAAA;AACT;AACF;QACA,OAAO,KAAA;AACT;IACA,KAAK,MAAMA,KAAK+B,KAAO,CAAA;AACrB,QAAA,MAAMwB,MAAMH,IAAKpD,CAAAA,CAAAA,CAAAA;AACjB,QAAA,IAAIuD,GAAK,EAAA;YACP,OAAO,IAAA;AACT;AACF;IACA,OAAO,KAAA;AACT;;;;"}

package/dist/animation/joint_dynamics/controller.js

@@ -3,8 +3,18 @@ import { buildConstraints, buildSurfaceFaces } from './constraints.js';
 import { simulate, applyAngleLimits, applyResult } from './solver.js';
 import { Vector3, Quaternion, Matrix4x4, clamp01 } from '@zephyr3d/base';
 
-// High-level orchestrator — SPCRJointDynamicsController API
-class JointDynamicsSystemController {
+// High-level orchestrator - SPCRJointDynamicsController API
+/**
+ * High-level controller for joint dynamics simulation.
+ *
+ * This class manages the physics simulation for a hierarchy of bones, including constraints,
+ * colliders, and grabbers. It provides an API for initializing the system with bone data and
+ * transforms, stepping the simulation each frame, and modifying colliders and grabbers at runtime.
+ * The controller handles the internal state and logic for blending between animation and physics,
+ * applying forces, and enforcing constraints.
+ *
+ * @public
+ */ class JointDynamicsSystemController {
     _config;
     _pointsR = [];
     _pointsRW = [];
@@ -44,13 +54,13 @@ class JointDynamicsSystemController {
         this._config = config;
     }
     /**
-   * 初始化物理系统
-   * @param rootTransform 根骨骼的 transform（用于检测根运动）
-   * @param rootPoints 骨骼层级的根节点数组（可以有多个根，如裙子的多条链）
-   * @param pointTransforms 所有物理点的 transform 数组（顺序必须与 BoneNode.index 对应）
-   * @param colliders 碰撞器数组（球体/胶囊体）
-   * @param grabbers 抓取器数组（用于鼠标交互等）
-   * @param flatPlanes 平面限制器数组（如地板，防止穿透）
+   * Initializes the physics system.
+   * @param rootTransform - Root bone transform used to detect root motion.
+   * @param rootPoints - Root nodes of the bone hierarchy. Multiple roots are allowed.
+   * @param pointTransforms - Transform array for all physics points. Order must match `BoneNode.index`.
+   * @param colliders - Collider array (spheres/capsules).
+   * @param grabbers - Grabber array used for interactions such as mouse dragging.
+   * @param flatPlanes - Plane limiters such as the floor to prevent penetration.
    */ initialize(rootTransform, rootPoints, pointTransforms, colliders, grabbers, flatPlanes) {
         this._rootTransform = rootTransform;
         this._pointTransforms = pointTransforms;
@@ -61,7 +71,7 @@ class JointDynamicsSystemController {
         this._surfaceConstraints = buildSurfaceFaces(rootPoints, this._config.constraintOptions.isLoop);
         // Flatten bone hierarchy to point list, build parent map
         const allPoints = [];
-        const parentMap = new Map(); // child index → parent index
+        const parentMap = new Map(); // child index -> parent index
         function walk(node) {
             allPoints.push(node);
             for (const c of node.children){
@@ -141,9 +151,10 @@ class JointDynamicsSystemController {
         this._initialized = true;
     }
     /**
-   * 执行一帧物理模拟
-   * 内部流程：读取当前 transform → 运行 Verlet 积分和约束求解 → 写回 transform
-   * @param deltaTime 帧间隔时间（秒）。内部会被 subSteps 细分
+   * Advances the simulation by one frame.
+   * Internal flow: read current transforms, run Verlet integration and constraint solving,
+   * then write the result back to the transforms.
+   * @param deltaTime - Frame delta time in seconds. Internally subdivided by `subSteps`.
    */ step(deltaTime) {
         if (!this._initialized || !this._rootTransform) {
             return;
@@ -219,9 +230,9 @@ class JointDynamicsSystemController {
         this._previousRootRotation = rootRot;
     }
     /**
-   * 获取所有点的模拟结果（世界坐标位置和旋转）
-   * 通常不需要手动调用——step() 已经自动写回 transform。
-   * 适用于需要在不写回 transform 的情况下读取物理结果的场景。
+   * Returns the simulated results for all points as world-space positions and rotations.
+   * Usually this does not need to be called manually because `step()` already writes the
+   * output back to the transforms.
    */ getResults() {
         const transformRots = this._pointTransforms.map((t)=>t.getWorldRotation());
         const transformLocalRots = this._pointTransforms.map((t)=>t.getLocalRotation());
@@ -232,9 +243,9 @@ class JointDynamicsSystemController {
             }));
     }
     /**
-   * 瞬移补偿——在角色传送/瞬移后调用
-   * 将上一帧的根骨骼位置和旋转设为当前值，
-   * 使下一帧的根运动增量为零，避免物理点因巨大位移而弹射。
+   * Compensates for teleportation by resetting the previous root transform to the current one.
+   * Call this after a character warp or teleport to avoid a large root-motion impulse on the
+   * next simulation step.
    */ warp() {
         if (!this._rootTransform) {
             return;
@@ -243,9 +254,9 @@ class JointDynamicsSystemController {
         this._previousRootRotation = this._rootTransform.getWorldRotation();
     }
     /**
-   * 重置所有物理状态
-   * 将所有点的模拟位置重置为当前 transform 位置，清除速度和抓取状态。
-   * 适用于场景切换或需要消除所有物理运动的场景。
+   * Resets all physics state.
+   * Each simulated point is snapped back to the current transform position and grab state
+   * is cleared.
    */ reset() {
         for(let i = 0; i < this._pointsRW.length; i++){
             const pos = this._pointTransforms[i].getWorldPosition();
@@ -256,9 +267,9 @@ class JointDynamicsSystemController {
         this._fakeWaveCounter = 0;
     }
     /**
-   * 释放固定点为动态点（如脱衣、布料脱落）
-   * 将 weight 从 0 改为 1，同时重置该点的模拟状态避免瞬间弹射。
-   * @param index 点的索引
+   * Releases a fixed point so it becomes dynamic, for example when cloth is detached.
+   * The point state is reset to avoid a sudden impulse.
+   * @param index - Point index.
    */ releasePoint(index) {
         if (index < 0 || index >= this._pointsR.length) {
             return;
@@ -270,9 +281,9 @@ class JointDynamicsSystemController {
         this._pointsRW[index].grabberIndex = -1;
     }
     /**
-   * 将动态点重新固定为跟随动画（如重新穿戴）
-   * 将 weight 从 1 改为 0，清除抓取状态。
-   * @param index 点的索引
+   * Fixes a dynamic point back to the animation pose, for example when an item is reattached.
+   * The point grab state is cleared.
+   * @param index - Point index.
    */ fixPoint(index) {
         if (index < 0 || index >= this._pointsR.length) {
             return;
@@ -281,43 +292,46 @@ class JointDynamicsSystemController {
         this._pointsRW[index].grabberIndex = -1;
     }
     /**
-   * 查询某个点是否为固定状态（weight=0，跟随动画）
-   * @param index 点的索引
+   * Returns whether a point is fixed to animation (`weight = 0`).
+   * @param index - Point index.
    */ isPointFixed(index) {
         if (index < 0 || index >= this._pointsR.length) {
             return false;
         }
         return this._pointsR[index].weight <= EPSILON;
     }
-    /** 获取物理点总数 */ get pointCount() {
+    /** Gets the total number of physics points. */ get pointCount() {
         return this._pointsR.length;
     }
     /**
-   * 渐入物理——从动画姿态平滑过渡到物理模拟
-   * blendRatio 从 1（纯动画）渐变到 0（纯物理）
-   * @param seconds 过渡时长（秒）
+   * Fades physics in by blending from animation pose to simulation.
+   * `blendRatio` moves from `1` (animation only) to `0` (physics only).
+   * @param seconds - Transition duration in seconds.
    */ fadeIn(seconds) {
         this._fadeState = 'in';
         this._fadeTimer = 0;
         this._fadeDuration = seconds;
     }
     /**
-   * 渐出物理——从物理模拟平滑过渡回动画姿态
-   * blendRatio 从 0（纯物理）渐变到 1（纯动画）
-   * @param seconds 过渡时长（秒）
+   * Fades physics out by blending from simulation back to animation pose.
+   * `blendRatio` moves from `0` (physics only) to `1` (animation only).
+   * @param seconds - Transition duration in seconds.
    */ fadeOut(seconds) {
         this._fadeState = 'out';
         this._fadeTimer = 0;
         this._fadeDuration = seconds;
     }
     /**
-   * 设置全局风力向量
-   * 风力会按每个点的 windForceScale 和质量进行缩放
-   * @param wind 风力向量（世界坐标）
+   * Sets the global wind force vector.
+   * The final wind contribution is still scaled per point by `windForceScale` and mass.
+   * @param wind - Wind vector in world space.
    */ setWindForce(wind) {
         this._config.windForce = wind;
     }
-    /** Enable/disable broad-phase pruning for runtime performance comparison */ setBroadPhaseEnabled(enabled) {
+    /**
+   * Enable/disable broad-phase pruning for runtime performance comparison
+   * @param enabled - `true` to enable broad-phase, `false` to disable.
+   */ setBroadPhaseEnabled(enabled) {
         this._config.enableBroadPhase = enabled;
     }
     /** The blend ratio for the physics simulation */ get blendRatio() {
@@ -327,9 +341,10 @@ class JointDynamicsSystemController {
         this._config.blendRatio = clamp01(value);
     }
     /**
-   * 暂停/恢复物理模拟
-   * 暂停时仍会跟随根骨骼运动，但不进行力学积分和约束求解
-   * @param paused true=暂停, false=恢复
+   * Pauses or resumes the physics simulation.
+   * While paused, the system still follows root motion but skips force integration and
+   * constraint solving.
+   * @param paused - `true` to pause, `false` to resume.
    */ setPaused(paused) {
         this._isPaused = paused;
     }
@@ -337,6 +352,11 @@ class JointDynamicsSystemController {
    * Enable or disable a collider by current array index.
    * Transform state is still read from the collider's TransformAccess each frame.
    * Prefer setColliderEnabled(handle, enabled) for runtime-owned colliders.
+   *
+   * @param index - Collider index in the current array. Note that this may change when colliders are added or removed.
+   * @param enabled - `true` to enable the collider, `false` to disable it.
+   *
+   * @returns `true` if the index is valid and the collider was updated, `false` if the index is out of range.
    */ setColliderEnabledAt(index, enabled) {
         if (index >= 0 && index < this._collidersRW.length) {
             this._collidersRW[index].enabled = enabled ? 1 : 0;
@@ -346,6 +366,9 @@ class JointDynamicsSystemController {
     }
     /**
    * Enable or disable a runtime collider by stable handle.
+   *
+   * @param handle - Stable handle for the collider to enable or disable.
+   * @param enabled - `true` to enable the collider, `false` to disable it.
    * @returns true if the handle is still valid.
    */ setColliderEnabled(handle, enabled) {
         const index = this._getColliderIndex(handle);
@@ -356,6 +379,8 @@ class JointDynamicsSystemController {
     }
     /**
    * Add a collider at runtime.
+   * @param r - Read-only collider data such as shape and size.
+   * @param transform - TransformAccess that provides the collider's position and rotation each frame.
    * @returns A stable handle that remains valid until this collider is removed.
    */ addCollider(r, transform) {
         const id = this._nextColliderHandleId++;
@@ -371,6 +396,7 @@ class JointDynamicsSystemController {
     }
     /**
    * Remove a collider by stable handle.
+   * @param handle - Stable handle for the collider to remove.
    * @returns true if the collider existed and was removed.
    */ removeCollider(handle) {
         const index = this._getColliderIndex(handle);
@@ -381,6 +407,7 @@ class JointDynamicsSystemController {
     }
     /**
    * Remove a collider by current array index.
+   * @param index - Collider index in the current array. Note that this may change when colliders are added or removed.
    * Prefer removeCollider(handle) for runtime-owned colliders.
    */ removeColliderAt(index) {
         if (index < 0 || index >= this._collidersR.length) {
@@ -395,7 +422,9 @@ class JointDynamicsSystemController {
     }
     /**
    * Enable or disable a flat plane by current array index.
-   * Prefer setFlatPlaneEnabled(handle, enabled) for runtime-owned flat planes.
+   * @param index - Flat plane index in the current array. Note that this may change when flat planes are added or removed.
+   * @param enabled - `true` to enable the flat plane, `false` to disable it.
+   * @returns `true` if the index is valid and the flat plane was updated, `false` if the index is out of range.
    */ setFlatPlaneEnabledAt(index, enabled) {
         if (index < 0 || index >= this._flatPlaneAll.length) {
             return false;
@@ -406,6 +435,8 @@ class JointDynamicsSystemController {
     }
     /**
    * Enable or disable a runtime flat plane by stable handle.
+   * @param handle - Stable handle for the flat plane to enable or disable.
+   * @param enabled - `true` to enable the flat plane, `false` to disable it.
    * @returns true if the handle is still valid.
    */ setFlatPlaneEnabled(handle, enabled) {
         const index = this._getFlatPlaneIndex(handle);
@@ -416,6 +447,8 @@ class JointDynamicsSystemController {
     }
     /**
    * Add a flat plane at runtime.
+   * @param up - Up direction of the plane. The normal is computed as `Vector3.normalize(up)`.
+   * @param position - A point on the plane. The distance is computed as `-Vector3.dot(normal, position)`.
    * @returns A stable handle that remains valid until this flat plane is removed.
    */ addFlatPlane(up, position) {
         const id = this._nextFlatPlaneHandleId++;
@@ -435,6 +468,7 @@ class JointDynamicsSystemController {
     }
     /**
    * Remove a flat plane by stable handle.
+   * @param handle - Stable handle for the flat plane to remove.
    * @returns true if the flat plane existed and was removed.
    */ removeFlatPlane(handle) {
         const index = this._getFlatPlaneIndex(handle);
@@ -445,7 +479,8 @@ class JointDynamicsSystemController {
     }
     /**
    * Remove a flat plane by current array index.
-   * Prefer removeFlatPlane(handle) for runtime-owned flat planes.
+   * @param index - Flat plane index in the current array. Note that this may change when flat planes are added or removed.
+   * @returns true if the index was valid and the flat plane was removed, false if the index was out of range.
    */ removeFlatPlaneAt(index) {
         if (index < 0 || index >= this._flatPlaneAll.length) {
             return false;
@@ -461,6 +496,10 @@ class JointDynamicsSystemController {
    * Enable or disable a grabber by current array index.
    * Transform state is still read from the grabber's TransformAccess each frame.
    * Prefer setGrabberEnabled(handle, enabled) for runtime-owned grabbers.
+   *
+   * @param index - Grabber index in the current array. Note that this may change when grabbers are added or removed.
+   * @param enabled - `true` to enable the grabber, `false` to disable it.
+   * @returns `true` if the index is valid and the grabber was updated, `false` if the index is out of range.
    */ setGrabberEnabledAt(index, enabled) {
         if (index >= 0 && index < this._grabbersRW.length) {
             this._grabbersRW[index].enabled = enabled ? 1 : 0;
@@ -473,6 +512,8 @@ class JointDynamicsSystemController {
     }
     /**
    * Enable or disable a runtime grabber by stable handle.
+   * @param handle - Stable handle for the grabber to enable or disable.
+   * @param enabled - `true` to enable the grabber, `false` to disable it.
    * @returns true if the handle is still valid.
    */ setGrabberEnabled(handle, enabled) {
         const index = this._getGrabberIndex(handle);
@@ -483,6 +524,9 @@ class JointDynamicsSystemController {
     }
     /**
    * Add a grabber at runtime.
+   * @param r - Read-only grabber data such as interaction radius.
+   * @param transform - TransformAccess that provides the grabber's position each frame.
+   * @param enabled - Whether the grabber starts enabled. The grabber can still be moved by its transform while disabled, but it won't affect any points until enabled.
    * @returns A stable handle that remains valid until this grabber is removed.
    */ addGrabber(r, transform, enabled = false) {
         const id = this._nextGrabberHandleId++;
@@ -501,6 +545,7 @@ class JointDynamicsSystemController {
     }
     /**
    * Remove a grabber by stable handle.
+   * @param handle - Stable handle for the grabber to remove.
    * @returns true if the grabber existed and was removed.
    */ removeGrabber(handle) {
         const index = this._getGrabberIndex(handle);
@@ -512,6 +557,9 @@ class JointDynamicsSystemController {
     /**
    * Remove a grabber by current array index.
    * Prefer removeGrabber(handle) for runtime-owned grabbers.
+   *
+   * @param index - Grabber index in the current array. Note that this may change when grabbers are added or removed.
+   * @returns true if the index was valid and the grabber was removed, false if the index was out of range.
    */ removeGrabberAt(index) {
         if (index < 0 || index >= this._grabbersR.length) {
             return false;