Developer Guide

Developer Guide

For working on hsr_renderer.exe itself (editor / renderer / cooker).

Building (Windows)

build_hsr.bat        # cmake --build build --target hsr_renderer  (MSVC + Ninja)

do_build.bat sets the MSVC/SDK env directly when vcvars64.bat's vswhere lookup is broken. Output: build/hsr_renderer.exe (editor+cooker) and build/hsl_cook.exe (standalone cook CLI). The .exe is gitignored — ship it as a GitHub Release, never commit the binary.

Running

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

Useful env flags

Flag	Effect
HSR_VERBOSE=1	Verbose decode/cook logging to stderr.
HSR_ANIMDBG=1	Per-mesh animation-record diagnostics.
HSR_SANIMDBG=1	sanim track parse log (incl. [SANIM-UV] UVTransform).
HSR_EXPORT=1 HSR_EXPORT_QUIT=1	Headless cook of the loaded env, then exit.
HSR_NOUVSCROLLFAST=1	Force UV matrix-replay instead of the smooth scroll (regression toggle).
HSR_SKINCLIP_NAMEMAP=1	Restore old last-writer skin→clip binding (regression toggle).
HSR_SHOT/HSR_NOUI	Headless screenshot / no editor UI.

HSR_LIVE HTTP control (127.0.0.1:17890)

Load once, then drive via POST commands (used by the MCP bridge): at=<sec> (scrub+freeze anim time), dump=<idx> (full per-mesh extract + [COOK-ANIM]), camera/frame/screenshot, solo/hide mesh, set bg/fov/far.

The cook-preview — your device-free oracle

hsr_dump <meshIdx> (MCP) or dump=<idx> (HTTP) prints the mesh's exact cook result: processed world matrix + AABB, shader/blend/tint/tex, and [COOK-ANIM] = the precise device animation it will cook 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. Use it to confirm animation/shader fixes before ever cooking a full APK.

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.

IDA MCP tips

• Two databases: V79 and V205.2 libshell.so.i64. Confirm which is active with list_instances (ports vary), 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 (the project's workflow). No Co-Authored-By line on commits here.
• The claude goals/ planning docs stay uncommitted.

Related: Architecture · Animation System · Device Patching.