arkavo-org / arkavo-org/VRMMetalKit
Epic: Romero-style performance roadmap (10 prioritized optimizations)
- Dominant language
- Swift
- Stars
- 6
- Forks
- 2
- Avg merge
- 18h 51m
- Merged PRs (30d)
- 26
Description
## Source
Triaged from an external performance review that applies the id Software ("Romero / Carmack") cultural and engineering lens to VRMMetalKit. The roadmap is mirrored in `docs/PERF_ROADMAP.md` on branch `perf/romero-roadmap` for in-repo discoverability.
## Principle
> *"You don't ship a fast renderer. You ship a renderer, measure it, and then for the next six months you delete code until it's fast."*
## Prerequisite — must land first
- [ ] #156 — Benchmark CI regression gate. Romero rule #1: never optimise anything you haven't measured. Every item below claims an impact; none of those claims are real until we have a baseline.
## Items (priority order from report)
| # | Romero item | Issue | Status |
|---|---|---|---|
| 1 | Publish baselines | #156 | already filed |
| 2 | Outline pass merge (tile memory / instanced draws) | #192 | new |
| 3 | SpringBone sleep gate when avatar is at rest | #149 | already filed |
| 4 | MToon pipeline specialisation via `[[function_constant]]` | #193 | new |
| 5 | Mask-dispatch morph targets to face-region vertices | #194 | new (orthogonal to #150) |
| 6 | Split VRMVertex into position-only + attributes | #195 | new |
| 7 | Demote MToon fragment intermediates to `half` | #196 | new |
| 8 | Tile-memory shared render pass | folded into #192 | — |
| 9 | MPS Kalman for ARKit smoothing | #198 | new |
| 10 | Dual-quaternion joint palette | #197 | new |
| + | GPU occlusion queries for crowd avatars | #199 | new (extends #91 / #154) |
## Expected impact (from report — claims, not measurements)
- First three items: ~30–40 % frame-time reduction on a single-avatar scene.
- Full list: roughly 2× on crowd scenes where the priority system and occlusion culling compound.
- **All numbers are conjecture until #156 produces a baseline.**
## Cultural commitments the report calls out
- Every PR runs against a fixed reference scene (`AvatarSample_A_1.0.vrm.glb` is already in the repo).
- No performance regression merges without explicit sign-off.
- Publish a budget ("one avatar at 120 Hz on iPhone 15 Pro under 4 ms GPU" or similar) and defend it.
## Cross-references to existing in-flight work
- #88 — outline via ICBs (alternative architecture to #192's tile-memory merge; pick one)
- #91 — crowd scalability (umbrella for #199 + parts of #192)
- #124 — skinning dedup (prerequisite for #195 + #197)
- #125 — per-light dedup (prerequisite for #193 + #196)
- #154 — frustum culling refinement (precondition for #199)
- #155 — MToon maintenance (intersects #193 + #196)
- #150 — morph "skip when unchanged" (orthogonal to #194)
Contributor guide
Research direction
Start by reading docs/PERF_ROADMAP.md on branch perf/romero-roadmap and issue #156, which is the stated prerequisite for measuring the listed optimizations. Review the dependencies and alternatives in issues #192, #193, #195, #197, and #199, along with the fixed AvatarSample_A_1.0.vrm.glb reference scene. Done requires turning this broad roadmap into measured, separately actionable performance work rather than implementing one obvious change.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- computer-graphics, performance
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 18/100