arkavo-org / arkavo-org/VRMMetalKit

Verify and document SpringBone angle limit implementation

Open
#67 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.