arkavo-org / arkavo-org/VRMMetalKit

Add gravity physics examples and documentation

Open
#56 0 comments 0 reactions 0 assignees View on GitHub
documentation medium
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.