modwright 0.1.0

package/knowledge/cyberpunk2077/anims.method.yaml

@@ -0,0 +1,360 @@
+game: cyberpunk2077
+topic: anims.method
+title: working method for diagnosing custom FPP melee animation defects
+facts:
+  - id: cp2077.anims.method.find-which-layer-lies-before-touching-a-knob
+    claim: "When the game contradicts the authored data, find WHICH LAYER lies before touching any knob.
+      The pipeline has (at least) five places truth can diverge, each with its own ground-truth
+      tool, to be walked in order: what was authored (the build's own gates), what the engine
+      COMPOSES (serialize the animgraphs to answer state-to-clip questions directly), what
+      post-passes run (IK/constraints — the same serialized graphs, cross referenced against
+      tools\\redmod\\scripts to see which script raises a given weight source), what survives the
+      ENCODER (a per-bone authored-GLB vs shipped-.anims diff), and what the EYE actually weighs
+      (position and rotation, per frame, in the exact frame the engine draws, split along/across the
+      relevant axis) — because a number straddling a visibility threshold can produce \"perfect
+      here, broken there\" from identical underlying data."
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - layer-diagnosis
+      - ground-truth
+      - five-layers
+    detail: "The concrete case this method was written to generalize: the sway defect was chased for a
+      week by re-measuring the authoring layer before the encoder layer was checked directly and
+      turned out to be where the truth actually diverged."
+  - id: cp2077.anims.method.believe-the-eye-over-a-green-gate
+    claim: Believe the user's own visual report over a passing automated gate, then go find the layer
+      the existing gates do not model, rather than re-measuring the layers they already cover; a
+      gate only ever sees what its underlying model sees.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - user-report
+      - gate-limitation
+      - trust-the-eye
+    detail: "\"The gate is green and the user says it is wrong. Believe the user\" (a project's own
+      notes) is the concrete phrasing this rule generalizes."
+  - id: cp2077.anims.method.validate-a-gate-against-known-good-and-known-bad
+    claim: Before trusting any new measurement or gate, validate it against BOTH a known-good build and
+      a known-bad build; a gate that has never been observed to fail is not yet a trustworthy gate.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - gate-validation
+      - known-good
+      - known-bad
+    detail: "This re-calibration exercise directly found two real gate bugs: a gate that flagged
+      vanilla's own correct off-screen park as a failure, and a park-position gate blind to screen Y
+      that missed a hand resting at waist height."
+  - id: cp2077.anims.method.fix-at-the-source-not-downstream-compensation
+    claim: Making the underlying authored data immune to a defect (e.g. constant rotation channels that
+      the encoder cannot damage) beats every downstream compensation that tries to hide the same
+      defect (damping, twist cancellation, gain scheduling), because those compensations scale the
+      real signal and the defect's noise together and therefore trade roughly 1:1 rather than
+      actually fixing anything.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - fix-at-source
+      - downstream-compensation
+      - encoder
+    detail: See cp2077.anims.authoring.sway-damp-gain-tuning-superseded and
+      cp2077.anims.encoder.sway-gunrot-const-fix-verified-in-game for the concrete before/after pair
+      this rule is drawn from.
+  - id: cp2077.anims.method.never-burn-a-launch-on-what-a-render-or-graph-can-answer
+    claim: Resolve everything answerable offline — a serialized animgraph, a script measurement, or a
+      rendered preview (contact sheet or GIF) — BEFORE spending a game launch to test it; the
+      project's own sway root-cause diagnosis and fix used zero launches end to end and needed
+      exactly one launch to confirm the result.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - offline-first
+      - launch-cost
+      - preview-render
+    detail: Preview GIFs (rendered frames composited with PIL) are cited as letting the user reject
+      choreography before the single manual WolvenKit import click that a real launch requires.
+  - id: cp2077.anims.method.record-findings-and-correct-stale-comments-immediately
+    claim: Record a finding into the project's handoff documentation the moment it is proven, log
+      rollback identifiers (archive MD5 and .anims MD5) on every deploy, and correct stale comments
+      or claims IN PLACE rather than leaving them for a later reader to trip over — a single stale
+      comment ("block never sees these additives") nearly derailed a later graph reading before it
+      was found and retracted.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - documentation
+      - stale-comment
+      - rollback-identifier
+    detail: See cp2077.anims.graph.block-never-sees-additives-old-belief for the specific retracted
+      claim this rule is drawn from.
+  - id: cp2077.anims.method.identify-builds-by-anims-md5-never-mtime
+    claim: Identify a build by the MD5 of the shipped .anims file, never by archive file modification
+      time; the WolvenKit pack step can write a byte-different archive from logically identical
+      content, so mtime alone cannot distinguish which content is actually deployed.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - build-identification
+      - anims-md5
+      - archive-mtime
+    detail: "Concretely burned once: a rollback labeled as \"yesterday\" turned out to be byte-identical
+      to that day's own build rather than the intended prior state, because it had been
+      distinguished only by filename/mtime. MERGED from an equivalent process fact, which dates the
+      rule to 2026-08-21 and records that the same hash-over-mtime discipline is applied
+      independently in a cache deploy script (which hash-verifies both the rollback copy and the
+      final live-archive copy) and in a build script's deploy path — a project-wide convention
+      rather than a one-off fix. See cp2077.world.loot-container.deploy-verifies-with-md5-not-mtime
+      for the cache-specific instance."
+  - id: cp2077.anims.method.copy-live-archive-to-rollback-before-every-deploy
+    claim: Always copy the currently-live game archive into a rollback folder BEFORE deploying any new
+      build, every single time; skipping this once meant there was no byte-exact "yesterday" build
+      to diff against when a user reported moved hand positions, which materially slowed diagnosis.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - rollback
+      - deploy-discipline
+      - archive-backup
+    detail: "\"A rebuild can reproduce any past state, but only if you know which knobs were set — an
+      archive is the cheaper record\" (a project's notes). MERGED from an equivalent process fact (a
+      mesh deploy script's \"ALWAYS KEEP A ROLLBACK\" comment, dated 2026-08-21), which records the
+      same rule arising independently on the mesh side after a deploy overwrote the live archive
+      with nothing kept."
+  - id: cp2077.anims.method.measure-in-the-frame-the-engine-actually-draws
+    claim: Measure a quantity in the exact reference frame the engine uses to draw it — gun space for
+      the FPP weapon's placement, the live per-frame camera basis for on-screen hand travel — never
+      in a convenient proxy frame such as a bone the mesh happens to be parented to in the authoring
+      tool, or a frame-0-fixed camera basis.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - reference-frame
+      - gun-space
+      - camera-basis
+    detail: "Two concrete, separately discovered instances of the same mistake: sway slip measured for
+      weeks against the wrong bone (WeaponRight instead of gun space) reported the BETTER build as
+      worse; a candidate \"lunge\" clip's measured +0.81 to +0.95 m of hand travel collapsed to
+      +0.15/+0.17 m once measured in the live camera basis instead of a frame-0-fixed one, because
+      the camera itself was moving 0.836 m during the clip."
+  - id: cp2077.anims.method.rendered-images-outrank-scalar-metrics
+    claim: When a rendered image and a scalar gate disagree, trust the rendered image. Four separately
+      documented incidents on this project involved an aggregate or proxy scalar (a bounding-box
+      corner mistaken for a real mesh vertex, a min/max range unable to distinguish "left end down"
+      from "right end up", a metric that divided by the wrong axis) hiding exactly the thing it was
+      supposed to measure, caught only by looking at the actual rendered frame.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - rendered-image
+      - scalar-metric
+      - instrument-bug
+    detail: "\"A reviewer should weight rendered images over any scalar here\" (a project's own notes),
+      stated as a direct consequence of the four documented instrument-lying incidents."
+  - id: cp2077.anims.method.clear-matrix-basis-before-reading-a-composed-pose
+    claim: In Blender, a bone that a given action does not key retains whatever matrix_basis was last
+      written by a PRIOR script or action; reading a composed pose (for example base pose combined
+      with an additive) without first resetting every bone to identity leaks the previous
+      measurement's pose into the next one, silently producing nonsense results (one documented case
+      produced an 11-meter bone span and an infinite value).
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - blender
+      - matrix-basis
+      - pose-leak
+      - gotcha
+    detail: "Standing fix: reset all bones to identity at the top of any pose-reading helper function
+      before evaluating a composed pose."
+  - id: cp2077.anims.method.evaluated-get-is-a-live-view-not-a-snapshot
+    claim: Blender's `object.evaluated_get(depsgraph)` returns a LIVE view onto the current depsgraph
+      state, not a snapshot; reading it after mutating the rig within the same function compares a
+      pose against its own already-mutated self. This made one drift-check gate structurally
+      incapable of ever failing — it printed 0.00000 m on a blend whose arms were actually 0.18 m
+      out of place.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - blender
+      - evaluated-get
+      - live-view
+      - gate-defect
+    detail: The fix is to snapshot the source pose BY VALUE before touching anything in the rig; three
+      separate consequences of the live-view bug were found in one blend file (a pole-angle search
+      chasing a moving target, a second arm placed from the first arm's leftover state, and the
+      incapable-of-failing drift guard).
+  - id: cp2077.anims.method.trace-rotation-metric-has-a-resolution-floor
+    claim: The common bone-rotation-difference metric acos((tr(A^T B) - 1) / 2) has an approximate
+      0.1485-degree resolution floor on a rig whose bone matrices carry a small non-unit scale
+      (measured 0.9993 to 1.0003 on this rig, which the formula assumes away); comparing a pose to a
+      re-sample of ITSELF returns 0.0000 mm position but about 0.1485 degrees rotation, so any
+      rotation reading at or below roughly 0.15 degrees in this tooling means "indistinguishable
+      from zero," not a small but real difference.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - rotation-metric
+      - resolution-floor
+      - bone-scale
+    detail: "A related, separately fixed instrument bug: measuring the same rotation-difference metric
+      on RAW WORLD matrices inherits this ~2.4-2.5-degree floor, whereas measuring it on a
+      grip-space quantity (inv(weapon) @ hand) cancels the scale and reads cleanly — see
+      cp2077.anims.method.grip-space-metric-cancels-bone-scale."
+  - id: cp2077.anims.method.never-use-quaternion-rotation-difference-angle
+    claim: Never use Blender's `Quaternion.rotation_difference(...).angle` to compare two rotations for
+      similarity; due to quaternion double-cover it can report approximately 360 degrees for two
+      rotations that are actually identical (a sign-flipped representation of the same rotation).
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - blender
+      - quaternion
+      - rotation-difference
+      - gotcha
+    detail: Called out explicitly alongside the trace-formula resolution-floor caveat as a second,
+      independent way this project's rotation tooling can mislead if used carelessly.
+  - id: cp2077.anims.method.grip-space-metric-cancels-bone-scale
+    claim: Measuring a grip's fidelity via the grip-space quantity inv(weapon) @ hand cancels the rig's
+      small (approximately 0.999-1.0003) bone-matrix scale and reads a clean sub-degree number,
+      whereas the identical comparison performed on raw world matrices inherits the trace-formula's
+      roughly 2.4-2.5-degree resolution floor; prefer the grip-space form for any grip-fidelity
+      check.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - grip-space-metric
+      - bone-scale
+      - resolution-floor
+    detail: With this fix applied, a family of clips that previously read a spurious ~2.4-degree
+      difference under raw-world-matrix comparison read exactly 0.0 mm / 0.0 degrees under the
+      grip-space metric.
+  - id: cp2077.anims.method.treat-engine-silence-as-a-signal
+    claim: "When authoring onto a bone or channel that no vanilla clip of the relevant TYPE ever touches
+      (for example torso rotation inside an FPP melee ambient-sway additive), treat that consistent
+      silence as the engine speaking, not as an oversight to fill in. Ignoring this once cost a full
+      game launch: a build that put the entire sway correction onto Spine3 measured a perfect result
+      in Blender and rendered completely motionless in game."
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - engine-silence
+      - torso-rotation
+      - spine3
+      - launch-cost
+    detail: See cp2077.anims.authoring.engine-limit-fpp-additive-ignores-spine-and-shoulders for the
+      full concrete case this rule is named for.
+  - id: cp2077.anims.method.additive-silence-rule-is-scoped-to-additives
+    claim: The "treat engine silence as a signal" rule is scoped specifically to ADDITIVE clips.
+      Full-body BASE attack clips (combo/heavy/final) are a different animDatabase node type
+      (convertToAdditive = 0) and the engine DOES let them move Spine and shoulder bones; vanilla
+      attack clips simply choose not to, which is confirmed evidence of a design convention, not
+      proof of a hard engine restriction — and this distinction was verified by reading the
+      serialized animgraph directly before ruling on it, rather than assuming the additive-only
+      silence finding transferred to base clips by default.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - additive-scope
+      - base-clip
+      - torso
+      - design-convention
+    detail: This nuance exists specifically to prevent over-generalizing
+      cp2077.anims.method.treat-engine-silence-as-a-signal from the sway additive case to every
+      future silence observed in any clip type.
+  - id: cp2077.anims.method.one-parametric-attempt-then-hand-to-the-user
+    claim: After a parametric authoring approach has already failed once against a corrected, measured
+      specification, allow exactly ONE further parametric attempt; if the user rejects that attempt
+      too, switch to a user-hand-posed reference pose rather than continuing to tune parameters —
+      repeated parametric iteration against subjective adjective feedback ("half way", "back in
+      front") wastes iterations that a single hand-posed capture reliably resolves.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - parametric-tuning
+      - hand-posed
+      - iteration-limit
+    detail: See cp2077.anims.authoring.one-hand-posed-frame-beat-five-parametric-iterations for the
+      concrete before/after this rule generalizes from.
+  - id: cp2077.anims.method.validate-screen-geometry-gates-against-vanilla-first
+    claim: Before trusting a new screen-space gate (in-frame fraction, aim-dot alignment, park screen
+      position) on a custom build, run it against the PRISTINE VANILLA clip occupying that same
+      state slot; two real gate bugs were found only this way — a gate that flagged vanilla's own
+      correct off-screen park as a failure, and a park-position gate that was blind to screen Y and
+      missed a hand resting at waist height.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - screen-geometry-gate
+      - vanilla-calibration
+      - gate-bug
+    detail: This is the concrete application of
+      cp2077.anims.method.validate-a-gate-against-known-good-and-known-bad to screen-space rendering
+      gates specifically.
+  - id: cp2077.anims.method.instrument-the-game-dont-infer-from-screenshots
+    claim: When an in-game pose or transform is in question, read it directly with a lightweight in-game
+      logging probe (for example, logging a bone's position and axes in FPP-camera space at a fixed
+      cadence) rather than inferring it from screenshots; three separate game launches were spent
+      reading a weapon's pose off screenshots and getting the answer wrong each time, before this
+      rule was adopted.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - runtime-probe
+      - screenshot-inference
+      - instrumentation
+    detail: The probe technique this rule refers to logs the weapon's origin and three axes in FPP
+      camera space via a direct transform call, at a fixed sample rate, over a fixed post-trigger
+      window.
+  - id: cp2077.anims.method.grep-anim-feature-source-in-redmod-scripts
+    claim: To find WHICH script raises a given animation feature's weight (for example, proving that
+      melee FPP arms are pure FK by finding who raises the ikLeftArm feature), grep
+      tools\redmod\scripts for the feature name directly rather than trying to infer the answer from
+      the animgraph's node structure alone.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - anim-feature
+      - grep
+      - redmod-scripts
+      - ground-truth
+    detail: Concretely settled that ikLeftArm is raised only for climbing
+      (locomotionTransitions.script), confirming that the melee left-arm IK constraint node lives in
+      the Vault state and is inert in melee.
+  - id: cp2077.anims.method.gate-a-clip-against-the-specific-proven-impossible-approach
+    claim: Once an approach to a problem has been proven structurally impossible (for example, that no
+      single ambient-sway additive can serve every base pose without a base-dependent conjugation
+      once the shoulders above the arms are unreachable), encode a build-time GATE that asserts the
+      disproven approach was not silently reintroduced, rather than relying on it simply not being
+      re-attempted by memory.
+    status: inferred
+    source: ModWright research
+    tags:
+      - working-method
+      - proven-impossible
+      - regression-gate
+      - engine-limit
+    detail: 'Concrete example: the block-building script asserts that
+      Spine3/Spine2/Spine1/Spine/Hips/LeftShoulder/RightShoulder remain at identity on every touched
+      sway clip, specifically because the "sway survived" check alone (which Blender honors even on
+      Spine3) could not have caught a regression back into the disproven Spine3-carrier approach.'