arkavo-org / arkavo-org/VRMMetalKit

VRMMetalKit: rename VRMMesh / VRMPrimitive / VRMMaterial to VRMRenderable* for clarity vs GLTFMetalKit

Open Beginner friendly
#246 0 comments 0 reactions 0 assignees View on GitHub
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.