IK и стопы

Поправки, которые движок вносит в анимированную позу. IK-цепи — аспекты на костях: IK.TwoBone ставит конец конечности на цель (руку на рукоять, стопу на ступеньку), IK.LookAt поворачивает кость к цели (голову, турель). Стопы — стадия каждого Animator, anim.feet: какие кости — стопы, фиксация стопы, IK по земле и события шагов. В JS ничего не работает покадрово — аспекты описывают, движок решает.

Где они работают в кадре: updateBefore() → физика → аниматоры (клипы, root motion, варп, стопы) → update() → IK-цепи → динамические кости → скиннинг. Цель, которую игра двигает в update(), достигается в том же кадре; кость цепи, прочитанная в update(), всё ещё показывает позу до решения (читай её в updateBefore(), который видит финальную позу предыдущего кадра).

Обзор

const main = async () => {
  const scene = new Scene()
  const hero = await Model.load(asset('./hero.glb'))
  scene.add(hero)
  scene.open()
  hero.anim.playLoop('Idle')                                     // IK поправляет позу: что-то должно играть

  const grip = new Node()                                        // узел: движок читает его каждый кадр
  grip.position = [0.3, 1.2, 0.4]
  scene.add(grip)
  const hand = hero.bone('LeftHand')!.aspect(IK.TwoBone, { target: grip, pole: [0.6, 1.2, -1] })   // LeftArm ▸ LeftForeArm ▸ LeftHand
  hero.bone('Head')!.aspect(IK.LookAt, { target: scene.camera, axis: [0, 0, 1], limit: 60 })

  hand.ik.weight = 0.5                                           // плавно вмешать / вымешать
  console.log(`hand off its target: ${hand.ik.error.toFixed(3)} m`)

  hero.anim.feet.set({ lock: true, ik: true })                   // поставленные стопы стоят на месте; стопы на земле
  hero.anim.feet.onStep((side, at) => console.log(`${side} foot down at ${at.x.toFixed(2)}, ${at.z.toFixed(2)}`))
}
main()

Двухкостный IK — IK.TwoBone

bone.aspect(IK.TwoBone, { target?, pole?, rotation?, rotationWeight?, weight?, enabled?, anchor?, anchorTime?, anchorPin? })
bone.ik                     // аспект — каждая опция это живое свойство
bone.ik.error               // после последнего решения: метры, на которые конечная кость всё ещё не дотянулась до цели (0 = достигнута)

Прикрепляй к КОНЕЧНОЙ кости: цепь — это она, её родитель и её прародитель (плечо ▸ предплечье ▸ кисть). Прародитель и родитель поворачиваются так, чтобы начало конечной кости достигло target; цель вне досягаемости вытягивает конечность к ней, а error говорит, насколько она не дотянулась. Цепь принадлежит ригу кости — ближайшему предку, несущему Animator (каждая Model); голое дерево узлов получает Animator на своём верхнем узле. Отсоединение аспекта убирает цепь.

Look-at — IK.LookAt

bone.aspect(IK.LookAt, { target?, axis?, limit?, weight?, enabled? })
bone.lookAt                 // аспект (weight / enabled / error, как выше)

Прикрепляй к самой кости. Цель за пределами limit поворачивает кость на limit градусов к ней и не дальше.

Сокеты и привязанные цепи

anim.sockets(bone: Node | string, { [name]: Node | { position?, quaternion? } }, { set? }): Animator
anim.removeSocket(name, set?)
hand.aspect(IK.TwoBone, { anchor: 'grip_l', anchorTime?, anchorPin? })
clip.anchors(bone: string, { donor?, spans?: [from, to, socket, rotation?, pin?][] }): AnimationClip   // секунды
clip.clearAnchors(bone)
hand.ik.anchorDelta         // { distance (м), angle (рад) } — насколько живой сокет сдвинул руку относительно дубля

Для рук на оружии. Сокет — именованный фрейм на кости рига: Node (пустышка на оружии — читается каждый кадр, так что сокет на движущейся части следует за ней) или фиксированный { position, quaternion } в пространстве кости. Набор по умолчанию — ЖИВОЙ (оружие в руках); { set: 'tr15' } именует набор ДОНОРА — те же сокеты на оружии, на котором были созданы дубли. Привязанная цепь (anchor: 'grip_l' — target, pole и rotation тогда игнорируются) сохраняет позу анимированной руки относительно её сокета на доноре и воспроизводит её относительно живого: сдвинутую и повёрнутую на разницу двух сокетов, никогда не переделанную. rotationWeight — доля поворота сокета, которую она берёт.

Якорные отрезки клипа перемещают руку между сокетами, пока он играет: [from, to, socket] в секундах клипа ('' = свободна: рука едет на своём собственном суставе), rotation 0–1 (по умолчанию 1), pin 0–1 (по умолчанию 0 — рука на пути к магазину сохраняет собственное движение дубля). Между отрезками рука на собственном сокете цепи, удерживаемая там через anchorPin (0–1: 1 = точно на сокете, так что ничто в позе ниже не может её сдвинуть). Рука движется между сокетами на пружине с полупериодом anchorTime секунд. Клип без якорей не участвует; AnimationClip.from переносит отрезки, перетаймленные (без их pin, который откатывается к 0), а зеркальный клип сохраняет их на той же кости.

arms.anim.sockets('ik_hand_gun', { grip_r: gun.gripR, grip_l: gun.gripL, mag: gun.mag })
arms.anim.sockets('ik_hand_gun', { grip_l: { position: [0.03, -0.12, -0.05] } }, { set: 'tr15' })
arms.bone('hand_l')!.aspect(IK.TwoBone, { anchor: 'grip_l' })
arms.anim.clip('Reload')!.anchors('hand_l', { donor: 'tr15', spans: [[0.9, 1.4, 'mag'], [1.4, 2.0, ''], [2.0, 2.4, 'mag']] })

Стопы — anim.feet

anim.feet.set({ lock?, ik?, left?, right?, pelvis?, … })   // меняются только переданные ключи — чейнится
anim.feet.lock = true / anim.feet.ik = true / …             // каждая опция это ещё и свойство
anim.feet.options                                           // что было задано
anim.feet.state('left')     // FootState | undefined — { locked, weight, anchor: Vec3, target: Vec3 }, мировые
anim.feet.kneeAxis('left')  // откалиброванная ось шарнира колена (в локале бедра) + её разброс (рад); undefined = нет цепи ноги
anim.feet.onStep((side, position) => …) / anim.feet.offStep(cb)   // стопа поставлена: 'left' | 'right', мировой Vec3

onStep срабатывает для того, что показывает БАЗОВЫЙ слой, на каждом контакте клипа — метках контакта, которые пайплайн ассетов записывает в GLB (lecodes assets marks), или контактах, обнаруженных по движению, когда их нет; клип без контактов ничего не вызывает. state() — undefined, пока ничего не играло, и на хостах без стадии стоп. Locomotion задаёт стопы сам (фиксация включена по умолчанию).

Смотрите также

• Animator — клипы, циклы, one-shot'ы, слои
• Locomotion — движение персонажа, варп шага и ориентации
• DynamicBone — вторичное движение, решается после цепей
• Аспекты — update / updateBefore, порядок