Architecture

Architecture

How the whole system fits together. There is one binary (hsr_renderer.exe) 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.

        ┌────────────────────────────── hsr_renderer.exe ──────────────────────────────┐
        │                                                                               │
 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,   │  GROUND TRUTH)         │  ASMH/RENDTXTR encoders)  │   ASMH + scene.zip)
 .ovr)  │   └ *_parser.h     mats)    │                        │  + APK splice/sign        │
        │                                                                               │
        │   ui/editor.h  — ImGui-style editor (outliner, gizmos, Cook tab, timeline)     │
        │   HSR_LIVE HTTP server (127.0.0.1:17890)  ◄── 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 (ground truth)

src/render/vk_renderer.h is a Vulkan renderer that draws the source environment exactly as libshell would (per-material MeshShellEnv, reversed-Z depth, blend/cull derived from the authored material flags). 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, ASMH/HZAN animation, RENDTXTR textures (ASTC / R16G16B16A16 VAT), plus a scene.zip and a spliced+signed APK. The cook consumes the same decoded data the renderer uses, so "what you preview is what you cook."

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.

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 renderer's world state.
• 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. The desktop preview is ground truth; fix it before cook → device.
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.