arkavo-org / arkavo-org/VRMMetalKit
Add gravity physics examples and documentation
- Dominant language
- Swift
- Stars
- 6
- Forks
- 2
- Avg merge
- 18h 51m
- Merged PRs (30d)
- 26
Description
## Description
Create comprehensive documentation and examples for the per-joint gravity physics feature.
## Documentation Needed
### 1. User Guide Section
Add to README.md or create PHYSICS.md:
```markdown
## SpringBone Gravity Physics
VRMMetalKit supports per-joint gravity control for realistic hair and clothing simulation.
### Basic Usage
Each SpringBone joint has two gravity parameters:
- `gravityPower`: Multiplier for global gravity (0.0 = weightless, 1.0 = normal, 2.0 = heavy)
- `gravityDir`: Direction vector (default [0, -1, 0] = downward)
### Recommended Values
| Use Case | gravityPower | gravityDir | Effect |
|----------|--------------|------------|--------|
| Light hair | 0.3 - 0.5 | [0, -1, 0] | Floaty, bouncy |
| Normal hair | 0.7 - 1.0 | [0, -1, 0] | Natural fall |
| Clothing | 1.0 - 1.5 | [0, -1, 0] | Heavy drape |
| Ribbons | 0.3 - 0.8 | Custom | Artistic flow |
| Weightless | 0.0 | N/A | Zero gravity |
```
### 2. Code Examples
**Example 1: Light Hair**
```swift
var joint = VRMSpringJoint(node: hairBoneIndex)
joint.gravityPower = 0.4 // Light, floaty
joint.gravityDir = SIMD3(0, -1, 0)
```
**Example 2: Heavy Coat**
```swift
var joint = VRMSpringJoint(node: coatBoneIndex)
joint.gravityPower = 1.3 // Heavier fall
joint.gravityDir = SIMD3(0, -1, 0)
```
**Example 3: Custom Direction (Ribbon)**
```swift
var joint = VRMSpringJoint(node: ribbonBoneIndex)
joint.gravityPower = 0.5
joint.gravityDir = SIMD3(0.3, -0.7, 0.0) // Slight forward tilt
```
### 3. Example VRM Files
Create test models demonstrating:
- [ ] Character with light hair (`gravityPower = 0.4`)
- [ ] Character with heavy coat (`gravityPower = 1.3`)
- [ ] Character with ribbons (custom `gravityDir`)
- [ ] Comparison model (same character, different gravity values)
Place in `Tests/VRMMetalKitTests/TestData/Gravity/`
### 4. Visual Documentation
Add screenshots or video showing:
- [ ] Hair physics at different `gravityPower` values
- [ ] Cloth draping comparison
- [ ] Custom gravity direction effects
- [ ] Before/after comparison (global gravity vs. per-joint)
### 5. API Documentation
Add inline documentation:
```swift
/// Per-joint gravity parameters for SpringBone physics.
///
/// - `gravityPower`: Multiplier for global gravity. Typical values:
/// - 0.3-0.5: Light hair (floaty, bouncy)
/// - 0.7-1.0: Normal hair (natural fall)
/// - 1.0-1.5: Clothing (heavy drape)
/// - 0.0: Weightless (zero gravity)
///
/// - `gravityDir`: Normalized direction vector. Defaults to [0, -1, 0] (downward).
/// Use custom directions for artistic effects (ribbons, capes).
///
/// ## Example
/// ```swift
/// var joint = VRMSpringJoint(node: hairBoneIndex)
/// joint.gravityPower = 0.4 // Light, floaty hair
/// joint.gravityDir = SIMD3(0, -1, 0)
/// ```
public var gravityPower: Float = 0.0
public var gravityDir: SIMD3 = [0, -1, 0]
```
## Acceptance Criteria
- [ ] User guide section added
- [ ] At least 3 code examples
- [ ] Example VRM files (or note if not available)
- [ ] Visual documentation (screenshots/videos)
- [ ] Inline API documentation with examples
- [ ] Updated README.md with link to gravity documentation
## Related
PR #51 - Implement per-joint gravity for cloth and hair physics
Issue #54 - Complete PR checklist
Contributor guide
Research direction
Start by reading PR #51 and Issue #54, then inspect README.md and the VRMSpringJoint API declaration. Add the gravity user guide, three Swift examples, inline API documentation, README.md link, and the requested files under Tests/VRMMetalKitTests/TestData/Gravity/. Done means the acceptance checklist is complete, including visual documentation or a note explaining unavailable example models.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100