arkavo-org / arkavo-org/VRMMetalKit
VRMMetalKit: rename VRMMesh / VRMPrimitive / VRMMaterial to VRMRenderable* for clarity vs GLTFMetalKit
- Dominant language
- Swift
- Stars
- 6
- Forks
- 2
- Avg merge
- 18h 51m
- Merged PRs (30d)
- 26
Description
## Context
After PR #241 lands, VRMMetalKit and GLTFMetalKit coexist with parallel-but-distinct runtime types:
| VRMMetalKit (MToon) | GLTFMetalKit (PBR) |
|---|---|
| `VRMMesh` | `GLTFRenderableMesh` |
| `VRMPrimitive` | (rolled into GLTFRenderableMesh) |
| `VRMMaterial` | `GLTFRenderableMaterial` |
| `VRMVertex` | `GLTFRenderableVertex` / `GLTFSkinnedRenderableVertex` |
| `VRMSkin` | `GLTFRenderableSkin` |
| `VRMTexture` | (raw `MTLTexture`) |
The audit in PR #241 settled that **unifying these types would add abstraction cost without collapsing the layers where the cost lives** — different shaders (MToon vs PBR), different vertex layouts, different attribute requirements (UInt32 vs UInt16 joints, COLOR_0 vs tangent). The runtime types are intentionally distinct.
But the *names* read like duplicates. `VRMMesh` and `GLTFRenderableMesh` are siblings; the naming asymmetry obscures that.
## What's needed
Rename in VRMMetalKit, with typealiases for source compatibility:
- `VRMMesh` → `VRMRenderableMesh` (`public typealias VRMMesh = VRMRenderableMesh`)
- `VRMPrimitive` → `VRMRenderablePrimitive`
- `VRMMaterial` → `VRMRenderableMaterial`
- `VRMVertex` → `VRMRenderableVertex`
- `VRMSkin` → `VRMRenderableSkin`
- `VRMTexture` → `VRMRenderableTexture`
Update DocC catalog references. Update internal call sites to the new names. Keep typealiases for external consumers.
## Acceptance
- All 1441 existing VRMMetalKit tests pass.
- Public API surface unchanged via typealiases.
- The parallel relationship `VRMRenderableMesh` ↔ `GLTFRenderableMesh` is visually obvious in the type system.
## Estimate
~30 minutes for the rename + typealias additions. The risk is low — Swift's rename refactor handles call sites, and the typealiases catch anything missed.
Contributor guide
Research direction
Start by locating the public VRMMetalKit type declarations, internal call sites, and DocC catalog references for the six types named in the issue. Apply the new names while retaining the listed typealiases, then run the 1,441 VRMMetalKit tests and verify the public API remains source-compatible.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- computer-graphics
- Issue type
- Refactor
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100