Architecture

Architecture

How the whole system fits together. There is one binary that is both the desktop editor/renderer and the cooker, plus a set of MCP bridges for automation and a Magisk module for running a patched shell on the headset. It builds and runs on Windows, Linux and macOS (Vulkan everywhere; MoltenVK on macOS).

        ┌──────────────────────────────── hsr_renderer ────────────────────────────────┐
        │                                                                              │
 V79 env│   loaders/                render/                 cook/                      │  V205 APK
 (.apk  │   ├ opa_loader.h  ──────►  vk_renderer.h  ◄─────── hsl_cooker.h  ────────────┼──►  (RENDMESH/
 .opa   │   ├ gltf_loader.h  (scene, │ (Vulkan preview =      │ (RENDMESH/MATL/HSTF/    │   MATL/HSTF/
 .gltf  │   ├ scene_loader.h  anim,  │  PREVIEW COPY)         │  ASMH/RENDTXTR encoders)│   ASMH + scene.zip)
 .ovr)  │   └ *_parser.h     mats)   │                        │  + APK splice/sign      │
        │                                                                              │
        │   ui/editor.h — custom Blender-style toolkit (outliner, gizmos, Cook tab,    │
        │                 timeline; drawn through the renderer's own Vulkan)           │
        │   HSR_LIVE HTTP server (127.0.0.1:<port>)  ◄── MCP: hsr-renderer / hsr-world │
        └──────────────────────────────────────────────────────────────────────────────┘
                                                   │ cooked APK
                                                   ▼
                        Quest 2/3/Pro  ──  Magisk vrshell_hotswap (patched VrShell)
                                           ◄── MCP: quest-bridge / quest-ctl  (adb)

The three big subsystems

1. Desktop renderer (fast preview replica)

src/render/vk_renderer.h is a Vulkan renderer that draws the source environment exactly as libshell would: per-material MeshShellEnv shading, reversed-Z depth, blend/cull/cutout derived from the authored material flags (with the per-material alphatestthreshold), SpecIbl from the env's own IBL cubemaps, baked lightmaps. This is the reference: fix the desktop preview first, because it is the device-free way to see what an environment should look like. Node/skeletal/UV animation is evaluated on the CPU (opa_loader.h animate()) and streamed into mapped vertex buffers each frame.

2. Cooker (V79 → V205)

src/cook/hsl_cooker.h re-encodes the loaded scene into the modern HSL APK format: RENDMESH geometry, MATL materials, HSTF scene/transform components, HZAN (ACL) animation, RENDTXTR textures (lossless ASTC pass-through where the source is untouched, sRGB-tagged; per-material generated SPIR-V shaders for animated/cutout materials), plus a scene.zip and a spliced+signed APK. The cook consumes the same decoded data the renderer draws, so "what you preview is what you cook" — and the cooked APK can be re-opened in the same window ("Preview cooked (HSL)") to verify before it ever touches a device.

3. Device layer

The cooked APK runs on a headset whose VrShell is patched (far-clip removal, hold-to-fly, an HSL bridge). The patched shell is delivered by a Magisk module (vrshell_hotswap) that bind-mounts the patched VrShell.apk over the system one at boot. See Device Patching. (Porting itself does not require the patched shell — a stock headset loads the cooked env; the patches add far-clip freedom and live control.)

Automation bridges (MCP)

• hsr-renderer — drive the live desktop renderer: hsr_launch, hsr_dump (the per-mesh cook-preview), hsr_screenshot, hsr_listmesh, hsr_cmd (raw HSR_LIVE commands like at=<sec>).
• hsr-world — read/write the patched device shell's world state (anim clock, player position).
• quest-bridge / quest-ctl — adb-level device control (install, reload shell, logcat, screencap).
• ida-pro-mcp — read the V79 and V205 libshell.so databases (the authority for every format).

Golden rules baked into the codebase

1. IDA first. Every shader / format / blend / transform / animation decision is traced from libshell.so, not guessed. The V79 DB and the V205.2 DB are the two sources of truth.
2. Render-side first (for speed). Iterate in the desktop preview, then confirm on the headset — the Quest's libshell is the real renderer and the final authority; the replica can't always reproduce it.
3. Cook = preview. The cook pulls from the same decoded structures the renderer draws, and the [COOK-ANIM] cook-preview (hsr_dump) reports exactly what device shader/animation each mesh will cook to — device-free.

See also: Animation System · File Formats · Developer Guide · Device Patching.