nx_nxa_play.nx

nx_nxa_play.nx -- THE NXA POSE PLAYER: apply a POSE-library entry to a rigged NXA and evaluate linear-blend skinning over the WHOLE mesh, at the corpus's real dimensions. WHY THIS EXISTS (measured 2026-08-23). Every rigged asset we own carries SKEL+SKIN with exact weights, and nx_nxa_pose freezes ANIM channel-2 keyframes into a POSE library -- but NOTHING applied them: the only in-engine evaluator (nx_skeleton) was capped at 32 bones / 2048 verts against a corpus of 104-370 joints and 14,164-423,919 verts, so a real character could not be posed at all. That cap is now gone (capacity is declared from the asset); this organ is the consumer that makes the capability reachable. A blocker removed but uncalled is BUILT+UNWIRED. THE MATH IS THE SPEC'S, NOT A NEW ONE. knowledge/nxa_format_spec.md declares the normative runtime form: M x = D (x - bind_t) + bind_t + dt, where D is the world-delta rotation ABOUT THE BIND POSE and dt the world translation delta -- exact LBS with NO hierarchy walk at runtime. Expanded, that is an AFFINE per-joint transform: M x = D x + (bind_t - D bind_t + dt). So the shared-local-position form nx_skeleton already implements (sum_j w_j (R_j v + p_j)) is SUFFICIENT: set R_j = D_j and p_j = bind_t - D bind_t + dt. No second skinning path is created, and nx_skeleton's v1 note ("one local pos, valid when bind poses align") stops being a limit -- the per-joint bind offset is folded into p_j, which is exactly where an affine form puts it. UNITS ARE THE MEASURED TRAP, NAMED IN THE SPEC: VERT/SKEL binds are in 0.01 mm model units while the POSE/ANIM dt lanes are packed in MILLIMETERS to fit i16. A consumer MUST scale dt by 100 or every baked translation renders at 1% (the recorded symptom: forearms pinned at T-pose pivots). WEIGHTS: SKIN carries q12 weights summing 4096 (spec); nx_skeleton blends in fx256 summing 256. The conversion happens HERE, at the boundary, and RENORMALIZES: the truncation residual is added back to the largest influence so every vertex's weights sum to EXACTLY 256. Dropping the residual shrinks a vertex toward the origin -- a silent, uniform volume loss that reads as "the mesh got slightly smaller", which is precisely the kind of defect that never gets attributed. Usage: nx_nxa_play <in.nxa> [pose_id] (no pose_id, or a pose_id absent from the library => the IDENTITY pose, which by construction reproduces bind pose exactly -- the neg-control) Exits: 0 ok | 2 usage | 3 refused-by-name | 5 no rigged sections