Developer Guide

Developer Guide

For working on the editor/renderer/cooker itself.

Building — all three OSes

Vendored deps are in-tree (Vulkan headers, volk, miniz, miniaudio, stb, ACL/RTM, fonts); CMake fetches GLFW, astc-encoder and Opus. No Vulkan SDK needed — volk loads the driver at runtime.

# Windows (MSVC C++17 + Ninja), from hsr_renderer_cpp/:
build_hsr.bat                        # -> build/hsr_renderer.exe

# Linux:
sudo apt-get install -y cmake ninja-build libvulkan-dev \
  libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libwayland-dev libxkbcommon-dev
cmake -S hsr_renderer_cpp -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --target hsr_renderer

# macOS:
brew install molten-vk ninja
cmake -S hsr_renderer_cpp -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --target hsr_renderer

• SIMD: texture encoding (astcenc) defaults to SSE4.1 on x86-64 (runs on any 64-bit CPU) and NEON on arm64. -DHSR_AVX2=ON = ~1.3× faster cooks, needs a 2013+ CPU (shipped binaries stay compatible — this is exactly GitHub issue #1).
• Fonts: the UI probes fonts/ and third_party/fonts/ beside the binary, then OS system fonts.
• CI: .github/workflows/build.yml builds Windows/Linux/macOS and attaches artifacts to v* tag releases (Windows zip, Linux AppImage + tar.gz, macOS dmg with MoltenVK bundled).
• The binaries are gitignored — ship them as GitHub Releases, never commit them.
• Crash handling: Windows gets a symbolized SEH stack (needs the PDB), POSIX a backtrace() — both write _crash.txt beside the binary.

Running

Drag an env onto the binary, or hsr_renderer <env.apk|.opa|.gltf.ovrscene>.

Useful env flags

Flag	Effect
HSR_VERBOSE=1	Verbose decode/cook logging to stderr.
HSR_EXPORT=1 HSR_EXPORT_QUIT=1	Headless cook of the loaded env (includes the saved session), then exit.
HSR_NOINSTALL=1	Skip the auto-install after a cook.
HSR_SHOT=out.png / HSR_NOUI=1	Headless screenshot / no editor UI.
HSR_ANIMTIME=<sec>	Pin every animation to a fixed time (deterministic captures / A-B diffs).
HSR_LIVE=<port>	HTTP control server (below).
HSR_ANIMDBG / HSR_SANIMDBG / HSR_FLIPDBG / HSR_SHADDBG	Animation / sanim / flipbook / shader-pick diagnostics.
HSR_ACLVERIFY=1	Cook: decode every compressed HZANIM clip back and print the roundtrip error.
HSR_NOHZ=1	Diag: cook with skinned animation off (isolate an HZANIM problem).
HSR_COOK_PREVIEW=1	After a cook, auto-launch a second instance previewing the cooked APK.

HSR_LIVE HTTP control

HSR_LIVE=17890 starts a localhost HTTP server (all platforms): the renderer loads once and you drive it with POSTed command lines — cam=x,y,z,yaw,pitch, shot=path.png, at=<sec> (scrub+pin anim time; at=-1 resumes), dump=<idx>, listmesh, farscan, solomesh=, hidemat=, quit. This is what the MCP bridge drives.

The cook-preview — your device-free oracle

dump=<idx> (HTTP) or hsr_dump (MCP) prints a mesh's exact cook result: processed world matrix + AABB, shader/blend/tint/tex, and [COOK-ANIM] — the precise device animation it cooks to (UV-SCROLL / FLIPBOOK-UVMATRIX / HZANIM-SKINNED / RIGID-HZANIM / STATIC / …). It calls the same extractors as the real cook, so it is authoritative without a device.

Working method (non-negotiable)

1. IDA first — trace the exact libshell logic (V79 DB + V205.2 DB) before any format/shader/ blend/transform/anim change. Don't guess-and-iterate.
2. Render-side first — reproduce & fix in the desktop preview (ground truth), then cook → device.
3. Test before trust — verify with the cook-preview and/or on-device; don't mark work done on assumption. Compare numbers (dumps, UV rates, azimuth sweeps), not just screenshots.

IDA MCP tips

• Two databases: V79 and V205.2 libshell.so.i64. Confirm which is active with list_instances, then select_instance.
• Never run whole-binary search_text/find_bytes on the ~30 MB libshell (it wedges). Use find_regex on strings + xrefs_to + decompile by address. Rename functions as you go.

Repo conventions

• Commit to master. No Co-Authored-By line on commits here.
• Source is public; binaries ship via Releases.

Related: Architecture · Animation System · Device Patching.