arkavo-org / arkavo-org/VRMMetalKit

Epic: Romero-style performance roadmap (10 prioritized optimizations)

Open
#200 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

## 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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.