modwright 0.1.0

package/knowledge/cyberpunk2077/anims.encoder.yaml

@@ -0,0 +1,156 @@
+game: cyberpunk2077
+topic: anims.encoder
+title: what the WolvenKit .anims encoder does to authored channels
+facts:
+  - id: cp2077.anims.encoder.damage-scoped-to-reauthored-clips-not-untouched-ones
+    claim: The "1.3-3.3 degree rotation damage on gun-space/IK bones" finding applies only to
+      RE-AUTHORED clips. On the 43 untouched vanilla attack clips shipped as-is (no data changed),
+      the worst measured shipped-vs-vanilla damage is 0.171 mm / 0.074 degrees on drawn bones and
+      0.149 mm / 0.069 degrees in gun space — near the measurement floor, not a real defect.
+    status: inferred
+    source: ModWright research
+    tags:
+      - encoder
+      - rotation
+      - untouched-clips
+      - reauthored-clips
+      - scoping
+    detail: An earlier blanket phrasing of the encoder rule ("the encoder butchers rotations on
+      gun-space/IK bones") needed the qualifier "in RE-AUTHORED clips, whose constant channels the
+      pipeline collapses to zero" — see
+      cp2077.anims.encoder.reauthoring-collapses-constant-channels. This fact SCOPES
+      cp2077.anims.roundtrip.encoder-rotation-noise, which carries the per-bone damage measurement
+      itself.
+  - id: cp2077.anims.encoder.reauthoring-collapses-constant-channels
+    claim: "Re-authoring a clip (even an identity-delta edit) collapses its numConstAnimKeys count to 0
+      on every touched bone (measured: block 284 -> 0, melee_idlepose 246 -> 0), removing the
+      constant-channel encoding that would otherwise protect a non-moving bone from rotation
+      quantization noise; an untouched clip instead keeps or even gains constant keys (measured
+      example: combo_attack_01 219 -> 438 after an unrelated round trip)."
+    status: inferred
+    source: ModWright research
+    tags:
+      - numconstankeys
+      - constant-channel
+      - encoder
+      - reauthoring
+      - collapse
+    detail: This is the mechanism-level reason re-authored clips are more vulnerable to encoder rotation
+      noise than untouched ones, and it is the basis of the mitigation in
+      cp2077.anims.encoder.constant-channel-restoration-mitigation.
+  - id: cp2077.anims.encoder.phantom-turn-mechanism
+    claim: The encoder's rotation noise on arms_gun_space pivots the drawn weapon about the gun-space
+      origin (near the right fist); at the left grip point this produces an error vector whose
+      magnitude depends on the noise angle and the base pose's own left-grip offset from gun space,
+      measured per base as 13.4 mm (melee_idlepose), 12.4 mm (block), 12.8 mm (melee_crouchpose),
+      12.9 mm (melee_safepose), rising to about 22 mm in the combat-additive variant.
+    status: inferred
+    source: ModWright research
+    tags:
+      - phantom-turn
+      - gun-space
+      - encoder
+      - left-grip
+      - base-pose
+    detail: This explains why the block state (12.4 mm) could read as perfect to the user while the idle
+      (13.4-16 mm) read as broken from the same underlying per-bone rotation damage — the number
+      that separates "reads fine" from "reads broken" is a visibility threshold tied to framing and
+      attention, not a difference in clip content, which is why the chosen fix removes the phantom
+      turn everywhere rather than trying to explain the threshold.
+  - id: cp2077.anims.encoder.sway-gunrot-const-fix-verified-in-game
+    claim: "SWAY_GUNROT_CONST (a build-script switch, default ON): author the four ambient sway additive
+      clips with an identity ROTATION delta on the whole gun-space chain, both ik-target chains, and
+      the four Torso hand-IK JNT bones, leaving TRANSLATION untouched. Because constant channels
+      encode through the .anims round trip exactly, this removes the encoder's phantom weapon turn
+      at the source; the fix was confirmed in game as a clear improvement."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - sway-gunrot-const
+      - encoder
+      - constant-channel
+      - phantom-turn
+      - fix
+    supersedes: cp2077.anims.authoring.sway-damp-gain-tuning-superseded
+    detail: "Pre-encoder slip measured by _sway_sweep_ik.py on add_melee_idle: melee_idlepose 0.0147 m
+      -> 0.0000 m, block 0.0119 m -> 0.0035 m, melee_crouchpose 0.0116 m -> 0.0033 m, melee_safepose
+      0.0323 m -> 0.0164 m. The predicted shipped floor after import was ~2-4 mm everywhere the
+      weapon is visible (LeftArm's own residual 0.28 degrees over an arm length); the in-game
+      verdict confirmed the fix resolved the visible defect."
+  - id: cp2077.anims.encoder.sway-fix-costs-orientation-breathing
+    claim: The SWAY_GUNROT_CONST fix removes the ambient sway's roughly 2 degrees of weapon orientation
+      "breathing"; the additive becomes pure translation, and the ratio between vanilla's own
+      left/right sway travel (about 1.2) collapses to 1.0 in the fixed build.
+    status: inferred
+    source: ModWright research
+    tags:
+      - sway-gunrot-const
+      - cost
+      - orientation
+      - translation-only
+    detail: Recorded as an accepted trade-off alongside the fix, not separately judged in game on its
+      own terms.
+  - id: cp2077.anims.encoder.rotation-compression-hints-match-vanilla
+    claim: "The shipped file's rotation-compression settings (maxRotationCompression: 1) are identical
+      to vanilla's own encoding hints, so the measured rotation damage is not the result of a wrong
+      encoder setting on the mod's side — it is inherent to how a re-authored, genuinely-varying
+      rotation channel gets quantized."
+    status: inferred
+    source: ModWright research
+    tags:
+      - encoder
+      - compression-hints
+      - maxrotationcompression
+      - quantization
+    detail: Ruled out early in the investigation, before the constant-channel mechanism was understood,
+      as a way of eliminating "we configured something wrong" as the explanation.
+  - id: cp2077.anims.encoder.fast-reauthored-clips-survive-encoder-clean
+    claim: "A fast, genuinely rotating re-authored attack clip can survive the encoder essentially
+      exactly: combo_attack_01's drawn-weapon turn measured authored 98.089 degrees, matching the
+      shipped re-export at 98.089 degrees, with 0.000 degree / 0.00 mm worst-bone damage —
+      reproduced consistently across several rebuilds of that clip."
+    status: inferred
+    source: ModWright research
+    tags:
+      - encoder
+      - fast-clip
+      - drawn-weapon-turn
+      - reauthored
+      - exact
+    detail: This overturned an earlier fear (see
+      cp2077.anims.encoder.fast-swing-noise-invisible-old-belief) that fast swing content would also
+      suffer heavy encoder rotation damage; only NEAR-STILL frames (windup hold, dwell plateau,
+      terminal settle) turned out to be the dangerous regime.
+    supersedes: cp2077.anims.encoder.fast-swing-noise-invisible-old-belief
+  - id: cp2077.anims.encoder.fast-swing-noise-invisible-old-belief
+    claim: An earlier project note assumed that 2 degrees of encoder rotation noise is invisible inside
+      a fast swing, so gun-space rotation-const protection was not needed for attack clips (only for
+      the ambient sway).
+    status: contradicted
+    source: ModWright research
+    tags:
+      - encoder
+      - fast-swing
+      - dead-belief
+      - near-still-frames
+    detail: "The source calls the old note WRONG-WAY-ROUND: the dangerous frames of an attack clip are
+      the NEAR-STILL ones (wind-up hold, dwell plateau, terminal settle) — exactly the regime that
+      produced the sway phantom-turn bug — not the fast-motion frames the note assumed needed
+      protecting. The reviewer's instruction was to treat \"2 deg is invisible inside a fast swing\"
+      as a fallback, never as the plan."
+  - id: cp2077.anims.encoder.constant-channel-restoration-mitigation
+    claim: The general mitigation for a re-authored attack clip is to snap gun-space rotation channels
+      to exactly constant across any window where the authored rotation varies by less than about
+      0.5 degrees (a dwell plateau or terminal settle), and to restore constant channels on any bone
+      that does not move, rather than relying on fast motion alone to mask encoder noise.
+    status: inferred
+    source: ModWright research
+    tags:
+      - constant-channel
+      - mitigation
+      - dwell
+      - terminal-settle
+      - restoration
+    detail: This generalizes the SWAY_GUNROT_CONST fix (built for the four ambient sway clips) into a
+      rule for the attack-chain builder, which authors many more clips with their own
+      windup/dwell/terminal phases.