arkavo-org / arkavo-org/VRMMetalKit
Verify and document SpringBone angle limit implementation
- Dominant language
- Swift
- Stars
- 6
- Forks
- 2
- Avg merge
- 18h 51m
- Merged PRs (30d)
- 26
Description
## Issue Description
Need to verify that VRMMetalKit's XPBD-based SpringBone physics correctly implements angle limits (pitch/yaw constraints) as specified in the VRM 1.0 specification and compare behavior with UniVRM's implementation.
## Background
UniVRM uses Verlet integration with explicit angle limits:
```csharp
// UniVRM: VRM10SpringBoneJoint.cs
[SerializeField, Range(0, Mathf.PI)]
public float m_pitch = Mathf.PI;
[SerializeField, Range(0, Mathf.PI / 2)]
public float m_yaw = 0;
public UniGLTF.SpringBoneJobs.AnglelimitTypes m_anglelimitType;
```
VRMMetalKit uses XPBD (Extended Position-Based Dynamics) which may handle constraints differently.
## Investigation Required
1. **Locate angle limit implementation** in VRMMetalKit:
- Check `SpringBoneComputeSystem.swift`
- Check Metal compute shaders (`SpringBone*.metal`)
- Search for pitch/yaw constraint handling
2. **Compare with VRM 1.0 spec:**
- Verify angle limit types are supported
- Check pitch range: [0, π]
- Check yaw range: [0, π/2]
3. **Test behavior:**
- Create test VRM with angle limits
- Compare visual results with UniVRM
- Verify constraints are enforced correctly
## Expected Findings
One of the following:
- ✅ Angle limits are implemented and working correctly
- ⚠️ Angle limits are implemented differently in XPBD (document the approach)
- ❌ Angle limits are not implemented (needs implementation)
## Code Locations to Check
```swift
// Sources/VRMMetalKit/SpringBoneComputeSystem.swift
// Look for angle limit handling in update() method
// Sources/VRMMetalKit/Shaders/SpringBoneDistance.metal
// Check if distance constraints include angle limits
// Sources/VRMMetalKit/Core/VRMTypes.swift
// Check if VRMSpringBoneJoint has angle limit properties
```
## Acceptance Criteria
- [ ] Document whether angle limits are implemented
- [ ] If implemented, verify correctness against VRM 1.0 spec
- [ ] If not implemented, create follow-up issue for implementation
- [ ] Document any differences between XPBD and Verlet approaches
- [ ] Add test cases for angle limit behavior
- [ ] Update documentation with findings
## Reference
VRM 1.0 SpringBone specification:
https://github.com/vrm-c/vrm-specification/blob/master/specification/VRMC_springBone-1.0/README.md
UniVRM implementation:
- `UniVRM/Packages/VRM10/Runtime/Components/SpringBone/VRM10SpringBoneJoint.cs`
## Priority
**High** - Affects specification compliance and physics accuracy
## Related Issues
- Depends on: None
- Blocks: Full VRM 1.0 compliance verification
Contributor guide
Research direction
Start by inspecting Sources/VRMMetalKit/SpringBoneComputeSystem.swift, the SpringBone*.metal shaders, and Sources/VRMMetalKit/Core/VRMTypes.swift for pitch, yaw, and angle-limit handling. Compare the findings with the VRM 1.0 specification and UniVRM10SpringBoneJoint.cs, then create an angle-limited test VRM. Done means the implementation status, XPBD-versus-Verlet differences, specification compliance, test results, and any follow-up work are documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- computer-graphics, documentation, testing
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100