fix(springbone): segment per-substep host writes into per-substep slots (#396)

[arkavo-com]

Closes #396.

The substep loop rewrites globalParams, bindDirections and the collider buffers from the host on every substep, but only animatedRootPositions was segmented by substep index (the #278 fix). The other three were single regions every dispatch read at offset 0, which failed differently on each command-buffer path:

• Self-committed (synchronousSpringBone): each substep is committed immediately and nothing waits, so substep i+1's host writes landed while substep i was still reading them — the run-to-run divergence tracked as Flaky: SpringBoneRendererDeterminismTests fails ~1 run in 3 under parallel load — residual non-determinism after #283 #394.
• Shared-buffer: every substep is encoded before the caller commits, so no dispatch had executed by the time the last write landed and every substep read the final substep's values. Deterministic, silent, and a different simulation.

warmupPhysics already documents this exact race and pays a full GPU drain per step to dodge it; the runtime loop cannot afford that, so it segments instead.

Each buffer now carries maxSubstepsPerFrame slots at 256-byte aligned strides (the kernels bind them in the constant address space), written and bound at substepIndex * stride. Writers that are not per-substep — the load-time uploads and the once-per-frame foreign collider tail — broadcast to every slot, so a substep never reads a slot the current frame did not populate.

Verification

The #394 determinism test is green 3/3 over full parallel runs that failed 2/3 on the same machine before.

Both new tests were confirmed red-then-green by reverting the fix underneath them. Worth noting the first version of the content test was vacuous — it passed against a single-region build because a slot left holding a stale broadcast also merely differs from its neighbour. It now pins the actual interpolant per slot.

Baseline drift scales with substeps per frame, which is the signature this change should have and is independent evidence it is not perturbing something unrelated:

tier	substeps at dt=1/60	max drift
ultra (120 Hz)	2	3.85 mm
high (90 Hz)	~1.5	2.13 mm
medium (60 Hz)	~1	0.94 mm
low (30 Hz)	<= 1	unchanged

Only ultra and high exceeded the 1 mm gate. Regenerated in b9d1746. Sanity render of AvatarSample_U is unchanged.

Behaviour change

Per-substep collider and bind-direction interpolation now actually reaches the GPU, so early substeps see geometry partway through the frame instead of fully advanced.

SpringBoneRotationTests read bindDirections at offset 0 and now index the last substep's slot, which is where the frame's final direction lives. Those failures were a stale helper, not a regression — (0.707, -0.707, 0) is exactly the t=0.5 interpolant for a 90 degrees rotation with 2 substeps.

Arm-swing guard re-baselined (#397)

testU_armSwing_velocityCorrection_reducesReentryFrames moved from a 13/180 floor to 19/180, so its bound goes 16 -> 19 in this PR. Investigation on #397 established that this is a real shift in that configuration rather than a slipped guard:

• The velocity correction still engages. Stubbing applyVelocityCorrection to an early return on this branch gives 23/180 against 19/180 with it intact — a 4-frame benefit, versus 5 frames before.

• That guard runs augment: false — no synthetic colliders, so no swept CCD. It is the coarse-collider repro configuration, not the one SpringBone collision: coarse collider shapes cause systemic clipping (hair→forehead, hair→arms, arm→skirt) — needs holistic fidelity analysis #309/SpringBone: motion-transient cloth clipping (sleeve→arm, skirt→leg) needs CCD/substep work #313 shipped. On the augmented path (testU_armSwing_armColliders_catapultStaysBounded) this change took re-entry from 24-27 frames to a flat 9, peak unchanged:

  	pre (main)	post
  frames	24, 25, 26, 27	9, 9, 9, 9
  peak	20.8-24.3 mm	22.40 mm every run

• Why coarse got worse: the old collapse had every substep read the collider at its end-of-frame position, which during a fast swing put it ahead of its true mid-frame location and caught cloth early — an accidental, crude CCD. Correct per-substep interpolation removes that, exposing the ordinary discrete tunneling the synthetic colliders exist to fix.

Both configurations are also now bit-deterministic run to run. The jitter that guard's docs attribute to "Metal compute reductions / fast-math" was substantially the #394 race.

Full parallel suite is green 3/3 at --num-workers 14.

Scope note

globalParams is segmented for uniformity but was not contributing to the divergence: every substep writes byte-identical params today, because var params = globalParams copies a stale let and neither windPhase nor settlingFrames is written back to it. That staleness is a separate latent bug (wind phase never advances) and is left alone here.

#380 rewrites much of this area and does not fix this — a grep across its full diff for the interpolation and wait symbols returns zero touched lines — so expect a conflict if it lands first.

🤖 Generated with Claude Code

[gitar-bot]

Code Review ✅ Approved 1 resolved / 1 findings

Segments springbone per-substep host writes into dedicated slots to eliminate race conditions, addressing the foreign tail broadcast inefficiency. No issues found.

✅ 1 resolved

✅ Performance: Foreign tail broadcast to all 10 slots every frame is wasteful

📄 Sources/VRMMetalKit/SpringBoneComputeSystem.swift:427-441 📄 Sources/VRMMetalKit/SpringBoneComputeSystem.swift:629
writeForeignTail runs once per frame and now loops over all substepSlots (10) writing the foreign collider tail into every slot, but only slots [0, frameSubstepCount) are ever dispatched this frame — and since it is re-run each frame, unread higher slots never matter. In crowd/external-collider scenes this multiplies the per-frame tail memcpy by up to 10x versus the single write it replaced. frameSubstepCount is already computed (line 535) before this call (line 629), so the loop can be bounded to the slots that will actually be read. Load-time updateBindDirections/updateSphereColliders/updateCapsuleColliders broadcasts are one-time and fine.

_{Was this helpful? React with 👍 / 👎 | Gitar}