Skip to content

Feat: Add per-joint finger pose API#148

Open
1001Bits wants to merge 1 commit into
rollingrock:mainfrom
1001Bits:feat/per-joint-finger-api
Open

Feat: Add per-joint finger pose API#148
1001Bits wants to merge 1 commit into
rollingrock:mainfrom
1001Bits:feat/per-joint-finger-api

Conversation

@1001Bits

@1001Bits 1001Bits commented Feb 8, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Adds setHandPoseCustomJointPositions(tag, hand, values[15]) to the FRIK API for per-joint finger control
  • Accepts 15 float values (3 joints per finger: proximal, medial, distal) instead of 5 per-finger values
  • Enables mods to control each finger joint independently for more natural grip animations around objects
  • API version bumped from 2 to 3, fully backward compatible

Motivation

The existing setHandPoseCustomFingerPositions duplicates a single value across all 3 joints of each finger. This works for simple poses but doesn't allow independent joint control needed for realistic object gripping (e.g. wrapping fingers around items of different sizes).

FRIK internally already supports per-joint values — setHandPoseOverride(), HAND_FINGERS_POINTING_POSE[15], and calculateHandPose() all work per-bone. This PR simply exposes that capability through the public API.

Changes

  • FRIKApi.h: Bump FRIK_API_VERSION to 3, add setHandPoseCustomJointPositions function pointer
  • FRIKApi.cpp: Add wrapper function + function table entry
  • HandPose.h/cpp: Add setFingerJointPositions(isLeft, values[15]) internal function

Value ordering

Index 0-2:   Thumb   (proximal, medial, distal)
Index 3-5:   Index   (proximal, medial, distal)
Index 6-8:   Middle  (proximal, medial, distal)
Index 9-11:  Ring    (proximal, medial, distal)
Index 12-14: Pinky   (proximal, medial, distal)

Matches internal LEFT_HAND_FINGERS[] / RIGHT_HAND_FINGERS[] bone order. Values 0.0 = bent, 1.0 = straight.

Backward compatibility

New function pointer appended at end of FRIKApi struct. Existing v2 mods never access it. clearHandPose() works unchanged for both old and new API paths.

Expose per-joint finger control through the public API. The existing
setHandPoseCustomFingerPositions accepts 5 per-finger values that get
duplicated across all 3 joints. The new setHandPoseCustomJointPositions
accepts 15 values (3 per finger: proximal, medial, distal) for
fine-grained control needed by mods like Heisenberg (HIGGS F4VR port)
that animate individual finger joints during object grabbing.

Internally, FRIK already supports per-joint values (setHandPoseOverride,
HAND_FINGERS_POINTING_POSE, etc.) — this just exposes it through the API.

API version bumped from 2 to 3. Fully backward compatible: the new
function pointer is appended at the end of FRIKApi, existing v2 mods
are unaffected.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant