arkavo-org / arkavo-org/VRMMetalKit

Refactor VRMRenderer.swift into Smaller, Focused Classes

Open
#4 4 comments 0 reactions 0 assignees View on GitHub
enhancement maintainability refactoring technical-debt
Dominant language
Swift
Stars
6
Forks
2
Avg merge
18h 51m
Merged PRs (30d)
26

Description

# Refactor VRMRenderer.swift into Smaller, Focused Classes

**Labels:** critical, refactoring, technical-debt, maintainability

## Problem
The `VRMRenderer.swift` file has grown to 3,237 lines, significantly exceeding the recommended 500-1000 line limit. This violates the Single Responsibility Principle and makes the code difficult to understand, test, and maintain.

## Current State
- `VRMRenderer.swift`: 3,237 lines
- Multiple responsibilities mixed in one class:
- Pipeline state management
- Uniform buffer management
- Draw call execution
- Morph target system
- Skinning system
- SpringBone physics integration
- Performance tracking
- Debug rendering
- 2.5D rendering mode
- Sprite caching

## Impact
- High cognitive load for contributors
- Difficult to test individual components
- Merge conflicts more likely
- Harder to review pull requests
- Violates SOLID principles

## Other Large Files
- `VRMGeometry.swift`: 1,094 lines
- `VRMSkinning.swift`: 885 lines
- `VRMAnimationLoader.swift`: 779 lines

## Suggested Solution

### Phase 1: Extract Rendering Systems
```
VRMRenderer.swift (core: ~500 lines)
├── VRMPipelineManager.swift (~300 lines)
├── VRMUniformManager.swift (~200 lines)
├── VRMDrawCallExecutor.swift (~400 lines)
├── VRMMorphTargetRenderer.swift (~300 lines)
├── VRMSkinningRenderer.swift (~300 lines)
├── VRMSpringBoneRenderer.swift (~200 lines)
├── VRMSpriteRenderer.swift (~300 lines)
└── VRMDebugOverlay.swift (~200 lines)
```

### Phase 2: Define Clear Protocols
```swift
protocol RenderingSystem {
func setup(device: MTLDevice) throws
func update(deltaTime: Float)
func render(encoder: MTLRenderCommandEncoder, model: VRMModel)
}
```

### Benefits
- Easier to test - each system tested independently
- Better separation of concerns
- Easier to understand - smaller files
- Reduced merge conflicts
- Better code reuse
- Easier to extend

## Implementation Plan
- Week 1: Extract Pipeline Management
- Week 2: Extract Uniform Management
- Week 3: Extract Rendering Systems
- Week 4: Integration and Testing

## Acceptance Criteria
- [ ] No file exceeds 1000 lines
- [ ] Each class has single responsibility
- [ ] All extracted classes have unit tests
- [ ] Integration tests verify coordination
- [ ] Documentation updated
- [ ] No functionality lost
- [ ] Performance maintained or improved

**Priority:** Critical
**Effort:** Large (3-4 weeks)

Contributor guide

Open the contributing guide

Research direction

Start by reading VRMRenderer.swift and mapping its listed responsibilities against VRMGeometry.swift, VRMSkinning.swift, and VRMAnimationLoader.swift. Review the proposed extraction phases and protocol before deciding boundaries. The work is done when no file exceeds 1,000 lines, extracted classes have unit tests, integration tests verify coordination, documentation is updated, and functionality and performance are preserved.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
computer-graphics
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.