modwright 0.1.0

package/knowledge/cyberpunk2077/anims.graph.yaml

@@ -0,0 +1,629 @@
+game: cyberpunk2077
+topic: anims.graph
+title: player_melee.animgraph / player_base.animgraph serialization and state-to-clip mapping
+facts:
+  - id: cp2077.anims.graph.serialize-graphs-for-ground-truth
+    claim: Serializing player_melee.animgraph and player_base.animgraph with `WolvenKit convert
+      serialize` produces roughly 16 MB of JSON that answers state-to-clip and post-pass questions
+      in minutes; this is the reliable way to find out which clips actually play and which weight
+      sources drive a post-pass, rather than inferring either from clip names or record fields.
+    status: inferred
+    source: ModWright research
+    tags:
+      - animgraph
+      - serialize
+      - wolvenkit
+      - ground-truth
+      - state-to-clip
+    detail: Used to settle, among other things, that the state->clip mapping the project had assumed was
+      wrong twice (hold_loop_01 was assumed to be the standing base; melee_safepose, not
+      melee_crouchpose, is what crouch-still settles into).
+  - id: cp2077.anims.graph.record-index-equals-clip-index
+    claim: "One counter drives both the TweakDB attack record lookup and the clip CSV lookup:
+      meleeTransitions.script concatenates stateName + attackNumber to fetch the record (GetAttack),
+      and the same meleeAttackNumber value is written into slotData.comboNumber to select the clip."
+    status: inferred
+    source: ModWright research
+    tags:
+      - attacknumber
+      - record-lookup
+      - clip-lookup
+      - slotdata
+      - combonumber
+    detail: This is why the record and clip always stay in lockstep as the attack counter advances
+      through a chain.
+  - id: cp2077.anims.graph.five-swing-chain-old-belief
+    claim: An earlier project note stated that AttacksNumber = 4 produces a "5-swing chain" (4 combo
+      hits plus a Final attack).
+    status: contradicted
+    source: ModWright research
+    tags:
+      - attacksnumber
+      - swing-count
+      - off-by-one
+      - dead-belief
+    detail: Off by one. See cp2077.anims.graph.attacksnumber-n-gives-n-swings for the corrected rule,
+      confirmed independently by two script reachability analyses and matching both the user's own
+      4-swing spec and an in-game log reading "COMBO 0 / COMBO 1 / COMBO 2 / FINAL counter=3".
+  - id: cp2077.anims.graph.attacksnumber-n-gives-n-swings
+    claim: "AttacksNumber = N gives exactly N total swings: combo attacks occupy counters 0..N-2 and the
+      FINAL attack occupies counter N-1 (CheckIfFinalAttack evaluates to (counter+1) >=
+      AttacksNumber, checked against the counter BEFORE it increments)."
+    status: inferred
+    supersedes: cp2077.anims.graph.five-swing-chain-old-belief
+    source: ModWright research
+    tags:
+      - attacksnumber
+      - swing-count
+      - combo
+      - final-attack
+    detail: Raising AttacksNumber to N requires a record named MeleeFinalAttack(N-1); the combo record
+      at that same index is never consulted, because the final-attack transition list is evaluated
+      before the combo-attack list (see cp2077.anims.graph.final-wins-over-combo-at-boundary).
+  - id: cp2077.anims.graph.final-wins-over-combo-at-boundary
+    claim: At the top attack counter, both a combo-attack state and the final-attack state can be
+      enterable (a weapon family may author a combo record at that same index too), but the
+      final-attack state wins because statemachine_melee.tweak lists allMeleeFinalAttacks BEFORE
+      allMeleeComboAttacks in the meleeComboAttack.transitionTo array.
+    status: inferred
+    source: ModWright research
+    tags:
+      - final-attack
+      - combo-attack
+      - transition-order
+      - state-machine-priority
+    detail: No explicit priority/weight field was found on transitionTo entries (every
+      transitionCondition is an empty string), so ordered-list evaluation is inferred rather than
+      directly read off a priority field; it is corroborated by vanilla behavior at a lower
+      AttacksNumber and by the mod's own in-game log showing FINAL winning at the top counter.
+  - id: cp2077.anims.graph.hit-deflect-variant-selection-is-reactive
+    claim: The _hit and _deflect clip variants are chosen by two sibling PSM states inside Attack
+      (Attack -> Hit on CompositeSimultaneous[BoolFeature(MeleeData.hasHitAnim==1),
+      ExternalEvent(MeleeHitNPC)]; Attack -> Deflect similarly on MeleeHitStatic), each reading its
+      own CSV keyed by the SAME (attackType, comboNumber) pair as the base clip; selection is
+      reactive, on contact, not predictive.
+    status: inferred
+    source: ModWright research
+    tags:
+      - hit-variant
+      - deflect-variant
+      - csv
+      - reactive-selection
+      - crossfade
+    detail: Crossfade to Hit is 0.0667 s, to Deflect 0.0333 s. A swing that connects with nothing plays
+      the base clip to the end and never touches either variant.
+  - id: cp2077.anims.graph.hashitanim-hasdeflectanim-flags
+    claim: hasHitAnim and hasDeflectAnim both default to false in the Attack_Melee schema; Attacks.Slash
+      sets both true, and MacheteComboAttackAbstract / MacheteFinalAttackAbstract both derive from
+      Slash without overriding, so every light-chain swing built on that lineage needs both a _hit
+      and a _deflect variant authored.
+    status: inferred
+    source: ModWright research
+    tags:
+      - hashitanim
+      - hasdeflectanim
+      - slash
+      - variant-requirement
+    detail: For contrast, MacheteStrongAttackAbstract sets hasDeflectAnim=false / hasHitAnim=true, so a
+      heavy attack on that lineage needs only a _hit variant, not a _deflect one.
+  - id: cp2077.anims.graph.gameplay-hit-timing-is-record-side-only
+    claim: "Gameplay hit timing is 100% record-side and clip-independent: MeleeAttackEvents.OnUpdate
+      fires the hit the instant GetInStateTime() >= attackData.attackEffectDelay; no animEvent in
+      the clip gates it, so nothing an authored clip does can move when the gameplay hit lands —
+      only editing the record's attackEffectDelay can."
+    status: inferred
+    source: ModWright research
+    tags:
+      - gameplay-hit
+      - attackeffectdelay
+      - record-side
+      - clip-independent
+    detail: This is why the project routinely clones a record (e.g. the ComboAttack1 pattern) purely to
+      change attackEffectDelay when a swing's contact frame needs to move, rather than trying to
+      move an animEvent in the clip.
+  - id: cp2077.anims.graph.combo-pacing-is-clip-independent-via-retimer
+    claim: "The visual pacing of a combo swing is also largely clip-independent: the Attack Switch's
+      blend weight is literally the expression string `\"input > 0\"` over `\"startupDuration +
+      activeDuration + recoverDuration\"` (read directly out of the serialized animgraph JSON, no
+      bytecode decoding needed); a positive sum selects a three-segment retimer driven by the clip's
+      own animAnimEvent_Phase markers, so every combo swing under the machete records plays at a
+      fixed 1.834 s on screen regardless of the donor clip's own authored length."
+    status: inferred
+    source: ModWright research
+    tags:
+      - combo-attack
+      - retimer
+      - phase-marker
+      - expression-string
+      - pacing
+    detail: The retimer stretches the katana clips' three segments by 1.5x-2.7x per segment to hit the
+      fixed total. The machete FINAL leaves all three durations at 0/0/0, which routes it to a
+      whole-clip 1:1 path instead of the retimer.
+  - id: cp2077.anims.graph.melee-idlepose-is-universal-terminal-hub
+    claim: All 43 vanilla katana attack clips (15 base + 14 _hit + 14 _deflect) end EXACTLY on
+      melee_idlepose frame 0 (worst measured deviation 0.155 mm on drawn bones, 0.179 mm over all
+      152 bones); melee_idlepose, a 2-frame static pose, is the universal terminal hub for the whole
+      melee state machine — block_end, melee_crouch_to_idle, melee_safe_to_idle, melee_slide_end,
+      melee_equip and melee_sprint_stop all land on it too.
+    status: inferred
+    source: ModWright research
+    tags:
+      - melee_idlepose
+      - terminal-pose
+      - recovery
+      - universal-hub
+    detail: This measured convention is what makes "end every authored swing on our own re-posed idle"
+      the correct terminal target for a custom weapon's chain.
+  - id: cp2077.anims.graph.attack-clips-start-at-launching-states-own-pose
+    claim: "Attack clips do NOT share a common start pose; each starts exactly at the pose of the state
+      that launched it (idle, crouchpose, block, hold_loop, or safepose). Measured spread of
+      base-attack START poses across the whole set: median 331 mm / 114 degrees at RightHand, max
+      713 mm / 180 degrees."
+    status: inferred
+    source: ModWright research
+    tags:
+      - attack-clip
+      - start-pose
+      - launching-state
+      - no-shared-start
+    detail: "Concrete pairings measured: combo_attack_01 and jump_attack open at the idle; crouch_attack
+      at melee_crouchpose; block_attack at block; heavy_attack_01/02 at hold_loop_01/02; safe_attack
+      and sprint_attack at melee_safepose."
+  - id: cp2077.anims.graph.attack-clips-are-full-body-base-clips-not-additives
+    claim: Combo/heavy/final attack clips are full-body BASE clips (convertToAdditive = 0 on all 12 live
+      AnimDatabase nodes measured), a different node class from the ambient sway additives; despite
+      this, all 43 vanilla attack clips still hold Root/Trajectory/Hips/Spine..Spine3/
+      Neck/Head/legs at exact identity for their whole duration, moving only shoulder translations,
+      the arm chains, the weapon/gun-space/IK bones, and the FPP camera joints.
+    status: inferred
+    source: ModWright research
+    tags:
+      - attack-clip
+      - base-clip
+      - additive
+      - torso
+      - spine
+      - convert-to-additive
+    detail: Because these are base clips, not additives, the engine-limit rule that an FPP ADDITIVE only
+      reaches LeftArm/RightArm and below does not apply to them — Spine3 and the shoulders are
+      technically reachable in an attack clip, even though vanilla itself never uses that reach
+      (treated as a design convention per
+      cp2077.anims.method.additive-silence-rule-is-scoped-to-additives).
+  - id: cp2077.anims.graph.engine-cuts-in-a-window-not-at-authored-join-frame
+    claim: The engine does not cut a chained attack at the frame animators put the successor's frame 0
+      at; MeleeAttackGenericDecisions.ExitCondition allows exiting into the next attack (or
+      block/idle/a parry) any time state-time falls within [attackWindowClosed, idleTransitionTime]
+      once the matching input is pressed, so a late-chaining player can land up to 174 mm off the
+      authored join pose (measured on one swing's mapped cut window).
+    status: inferred
+    source: ModWright research
+    tags:
+      - cut-window
+      - exitcondition
+      - attackwindowclosed
+      - chain-pop
+      - late-chain
+    detail: A player who mashes the input cuts at the earliest allowed frame and lands on the authored
+      join almost exactly (0.0-0.3 mm on two measured swings); a player who chains late can pop by
+      up to 174 mm. Whether vanilla itself pops this way on a very late cut (measured up to 568 mm
+      under katana records) is unresolved — see
+      cp2077.anims.graph.inertialization-fields-unexercised.
+  - id: cp2077.anims.graph.inertialization-fields-unexercised
+    claim: animAnimNode_AnimDatabase nodes carry applyInertializationOnAnimSetSwap and pushSafeCutTag
+      fields that were found in the serialized graph but never investigated or exercised; whether
+      vanilla itself visibly pops on a very late chain cut, or some inertialization path smooths it,
+      is an open, unresolved question.
+    status: unverified
+    source: ModWright research
+    tags:
+      - inertialization
+      - animdatabase
+      - pushsafecuttag
+      - open-question
+    detail: "Proposed cheapest offline experiment: play the vanilla katana chain in Blender exactly as
+      the engine would sequence it (hard cut mid-clip to the next clip's frame 0) and see whether it
+      visibly pops there too."
+  - id: cp2077.anims.graph.entry-transition-is-hard-cut-zero-duration
+    claim: The global transition INTO the Attack state has duration 0 and canRequestInertialization 0
+      (also supportBlendFromPose 0), so if the current idle's grip pose differs from the launching
+      attack clip's own frame-0 pose, the very first rendered frame of the attack snaps
+      instantaneously with no blend.
+    status: inferred
+    source: ModWright research
+    tags:
+      - entry-transition
+      - hard-cut
+      - inertialization
+      - attack-entry
+    detail: "Measured concretely on this mod before its attack clips were re-authored: the re-posed
+      idle's grip span (0.5124 m) vs the pristine katana attack clips' own frame-0 span (0.0929 m)
+      is a 0.4195 m difference at the same joint — an instantaneous 0.42 m hand snap on the first
+      frame of any light attack, until the attack clip's own frame 0 was re-authored to match."
+  - id: cp2077.anims.graph.no-root-motion-in-melee-attack-clips
+    claim: motionExtraction is null and modelSpacePositionX/Y/Z are constant zero on every
+      combo/final/heavy clip across all nine measured player-FPP melee donor sets; there is no root
+      motion of any kind in a vanilla melee attack clip.
+    status: inferred
+    source: ModWright research
+    tags:
+      - root-motion
+      - motionextraction
+      - model-space-position
+      - no-root-motion
+    detail: "Practical consequence: any forward step, lunge or displacement for a custom finisher has to
+      be authored at the record/script level (e.g. RequestPlayerPositionAdjustment /
+      AddAttackImpulse), never via clip translation."
+  - id: cp2077.anims.graph.melee-fpp-arms-are-pure-fk
+    claim: "Melee FPP arms are pure FK: the left-arm animAnimNode_Ik2 in player_base.animgraph is
+      weight-gated by the ikLeftArm anim feature, which vanilla scripts raise ONLY for climbing
+      (locomotionTransitions.script:3457); the Ik2Constraint node itself lives in the Vault state,
+      not in any melee state."
+    status: inferred
+    source: ModWright research
+    tags:
+      - ik2
+      - ikleftarm
+      - fk
+      - vault-state
+      - anim-feature
+    detail: This was proven "without a launch" specifically by grepping tools\redmod\scripts for who
+      raises the anim feature, rather than assuming from graph structure alone (see
+      cp2077.anims.method.grep-anim-feature-source-in-redmod-scripts).
+  - id: cp2077.anims.graph.left-ik-jnt-overwritten-by-multipleparentconstraint
+    claim: Torso_LeftArm_Hand_IK_JNT is overwritten every frame by a weight-1 MultipleParentConstraint
+      blending arm_left_ik_offset (the gun-space chain) against Torso_World_LeftArm_Hand_IK_JNT via
+      the leftHandWorldSpace float track, which every vanilla clip holds at exactly 0 — so the
+      constraint's effective target is always arm_left_ik_offset, and any rotation or position
+      authored directly onto Torso_LeftArm_Hand_IK_JNT is discarded at runtime.
+    status: inferred
+    source: ModWright research
+    tags:
+      - torso-leftarm-hand-ik-jnt
+      - multipleparentconstraint
+      - lefthandworldspace
+      - gun-space
+    detail: Keep clip data on these JNT targets anyway — vault/climb states do read them, and matching
+      the vanilla invariant (leftHandWorldSpace held at 0) is what keeps melee behavior unaffected.
+  - id: cp2077.anims.graph.ik2-rebuilds-left-arm-from-cached-effector
+    claim: animAnimNode_Ik2, in the main (not state-gated) flow of player_base.animgraph, rebuilds
+      LeftArm/LeftForeArm every frame so that LeftHand reaches an effector cached from
+      Torso_LeftArm_Hand_IK_JNT; consequently, the in-game left-hand POSITION follows the clip's
+      arm_left_ik_offset target, not whatever pose is directly authored onto LeftArm/LeftForeArm.
+    status: inferred
+    source: ModWright research
+    tags:
+      - ik2
+      - left-arm
+      - effector
+      - arm-left-ik-offset
+      - gun-space
+    detail: This discovery is the reason the project's sway-measurement tooling switched to measuring
+      "what the engine will draw" (the ik target in gun space) rather than the authored LeftHand
+      bone, and it is the mechanistic root of why authoring an arm-only fix into the sway additive
+      could never have worked (see
+      cp2077.anims.authoring.no-base-independent-fix-for-full-ambient-sway).
+  - id: cp2077.anims.graph.block-never-sees-additives-old-belief
+    claim: An earlier project comment/belief held that the Block state never sees the ambient sway
+      additive machine — i.e. that a different, separate additive plays while blocking.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - block-state
+      - ambient-sway
+      - dead-belief
+      - stale-comment
+    detail: Retracted the same session it was disproven — the stale comment "nearly derailed the graph
+      reading" per the project's own working-method notes.
+  - id: cp2077.anims.graph.block-runs-same-additive-machine-as-idle
+    claim: "The Block state runs the exact SAME ambient-sway additive machine at the same weight (1) as
+      the standing idle: base melee_idlepose plus add_melee_idle out of combat, damped-blended to
+      add_melee_idle_combat in combat — the same instances also drive Ready, Targeting Throwable and
+      bodyslam."
+    status: inferred
+    supersedes: cp2077.anims.graph.block-never-sees-additives-old-belief
+    source: ModWright research
+    tags:
+      - block-state
+      - ambient-sway
+      - additive-machine
+      - ready-state
+    detail: This is why the sway fix (SWAY_GUNROT_CONST) helps the block's already-good reading too, and
+      why the block reading identical to the idle's under a shared additive was the strongest early
+      clue toward the eventual encoder root cause.
+  - id: cp2077.anims.graph.hold-loop-is-attack-charge-old-belief
+    claim: An earlier hypothesis treated hold_loop_01 as a possible better candidate for "what plays
+      while standing" than melee_idlepose, since it is a 21-frame loop rather than a 2-frame static
+      pose.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - hold-loop
+      - standing-base
+      - dead-belief
+    detail: Struck in place per the project's own doc-hygiene practice, so a later reader landing on the
+      open-questions section would not re-author against the wrong base.
+  - id: cp2077.anims.graph.hold-loop-is-attack-charge-not-standing-base
+    claim: hold_loop_01/02 is the ATTACK-CHARGE hold, entered via Ready > Hold on MeleeData.isHolding,
+      not the standing idle base.
+    status: inferred
+    supersedes: cp2077.anims.graph.hold-loop-is-attack-charge-old-belief
+    source: ModWright research
+    tags:
+      - hold-loop
+      - attack-charge
+      - meleedata-isholding
+      - ready-state
+    detail: Confirmed directly from the serialized player_melee.animgraph rather than inferred from clip
+      content.
+  - id: cp2077.anims.graph.add-block-family-are-directional-reactions
+    claim: The nine add_block_* additives (AdditiveWithoutFirstFrame type) are directional BLOCK
+      REACTIONS (up/down/left/right plus bullet deflects), not ambient sway, and are distinct from
+      the four continuous Additive-type ambient-sway clips (add_melee_idle, add_melee_idle_combat,
+      add_walk_melee_0, add_jog_melee_0).
+    status: inferred
+    source: ModWright research
+    tags:
+      - add-block
+      - directional-reaction
+      - additivewithoutfirstframe
+      - ambient-sway
+    detail: This distinction matters when deciding which additive family a given sway-related fix or
+      measurement should even touch.
+  - id: cp2077.anims.graph.safe-state-is-script-gated-not-idle-timer
+    claim: The Safe state (melee_safepose) is entered through a script gate (MeleeData.isSafe, set by
+      defaultTransition.script's ShouldEnterSafe on conditions like aiming at a friendly, terminals,
+      scanning, or takedowns), not by a plain "stood still long enough" idle timer; crouch-still
+      specifically settles into melee_safepose, not melee_crouchpose.
+    status: inferred
+    source: ModWright research
+    tags:
+      - safe-state
+      - meleedata-issafe
+      - crouch-still
+      - melee_safepose
+    detail: This corrected an earlier assumption that crouch-still used melee_crouchpose, which affected
+      where a crouch-related sway or grip fix needed to be pinned.
+  - id: cp2077.anims.graph.no-machete-anims-file-old-belief
+    claim: An earlier project note treated the non-prefixed default_melee_weapon.anims file as the
+      machete/chainsword/axe FPP anim set.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - machete
+      - default-melee-weapon
+      - dead-belief
+    detail: Wrong in three places in the project's own notes. See
+      cp2077.anims.graph.machete-plays-one-handed-blunt-set for the corrected mapping.
+  - id: cp2077.anims.graph.machete-plays-one-handed-blunt-set
+    claim: A depot-wide survey (regex over every content archive, 6451 unique .anims paths) found NO
+      pwa_machete/pma_machete, chainsword, axe or one-hand-blade player FPP set anywhere in the game
+      — the only "machete" resources are three NPC clips. Machete, axe, chainsword, one-hand blade
+      and one-hand blunt all share the single set
+      base\animations\weapon\one_handed_blunt\pwa_one_handed_blunt.anims (pma_ twin for male). The
+      priority and gating rule for that set is recorded at
+      cp2077.anims.sets.weapon-family-set-is-the-fallback; this fact records only the depot survey
+      that rules out a per-weapon file.
+    status: inferred
+    supersedes: cp2077.anims.graph.no-machete-anims-file-old-belief
+    source: ModWright research
+    tags:
+      - machete
+      - one-hand-blunt
+      - friendlyname
+      - animwrapper
+      - shared-set
+    detail: "default_melee_weapon.anims is a SEPARATE, always-mounted priority-200 fallback with only 17
+      float tracks and no Phase events at all — it must never be used as a donor for anything
+      requiring Phase-marker timing. Its own combo_attack_01/02 are left-arm actions with the weapon
+      hand nearly frozen (RightHand path 0.178 m vs LeftHand 1.386 m). The complete player-FPP melee
+      set list with gating variables was tabulated from the EP1 player ent:
+      w_melee_katana/pwa_katana, w_melee_knife + knife_thumb_override/pwa_knife,
+      w_melee_baton/pwa_baton, w_melee_one_hand_blunt + additives/pwa_one_handed_blunt,
+      w_two_hand_blunt/pwa_two_handed_blunt, w_melee_hammer/pwa_two_handed_hammer, w_melee_fists +
+      StrongArms/pwa_fists (all 128), mantis_blade and mono_wires at 128, dildo at 127, and the
+      ungated 200 trio default_melee_weapon / pwa_strongarms / pwa_katana_finisher."
+  - id: cp2077.anims.graph.custom-set-mount-priority-competitor
+    claim: A machete-derived custom weapon INHERITS friendlyName = w_melee_one_hand_blunt from its base
+      preset and sets no override, so the weapon-family set pwa_one_handed_blunt is co-mounted at
+      priority 128 whenever the weapon is out; a custom set at priority 127 therefore wins every
+      shared clip name by exactly ONE number, and every name it does not supply falls through to
+      that family set. Setting a unique friendlyName (e.g. w_melee_<mod>) on the custom weapon's own
+      item record removes the competitor entirely, at the cost of no longer inheriting anything from
+      that mount.
+    status: inferred
+    source: ModWright research
+    tags:
+      - priority
+      - animwrapper
+      - friendlyname
+      - fallback-order
+      - co-mount
+    detail: The priority ordering rule itself (lower number wins; sets override by shared clip NAME) is
+      cp2077.anims.sets.lower-priority-number-wins, and the fall-through order is
+      cp2077.anims.sets.weapon-family-set-is-the-fallback; this fact records only the custom-weapon
+      consequence of inheriting a base preset's friendlyName.
+  - id: cp2077.anims.graph.anim-set-gating-variable-is-native-old-belief
+    claim: An earlier project note observed that the gating AnimWrapper variable name for a per-weapon
+      anim set (e.g. w_melee_katana) appears in none of tools\redmod\tweaks and hypothesized it must
+      be native (C++) behavior with no moddable yaml lever.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - animwrapper
+      - friendlyname
+      - dead-belief
+      - native-hypothesis
+    detail: See cp2077.anims.sets.weapon-family-set-is-the-fallback for the resolved mechanism — the
+      gating variable is the weapon record's own friendlyName field, raised natively via
+      SetAnimWrapperWeight, and therefore fully moddable from yaml.
+  - id: cp2077.anims.graph.three-numbering-systems-for-swing-index
+    claim: 'Three different numbering conventions for "the same" swing index coexist and are the cause
+      of most stale documentation claims in this project: TweakDB attack records are 1-based
+      (MacheteComboAttack1..4), the attackName/state index is 0-based (MeleeComboAttack0..3), and
+      clip/CSV names are 1-based two-digit (combo_attack_01..09).'
+    status: inferred
+    source: ModWright research
+    tags:
+      - numbering-convention
+      - record-index
+      - clip-index
+      - attackname
+    detail: '"Never written down together before" per the source document; explicitly called out as the
+      single biggest source of off-by-one documentation errors across the project.'
+  - id: cp2077.anims.graph.sk-speedanim-subtree-is-dead-old-belief
+    claim: An earlier project belief held that the live animgraph only has 4 combo, 5 final and 2 heavy
+      attack slots, based on a subtree of literal-clip-name animAnimNode_SkSpeedAnim nodes.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - skspeedanim
+      - dead-subtree
+      - slot-count
+      - dead-belief
+    detail: Four separate research agents independently read this ceiling off the dead subtree before it
+      was checked against reachability.
+  - id: cp2077.anims.graph.real-swing-ceiling-is-nine-slot-csv
+    claim: "The literal-clip-name animAnimNode_SkSpeedAnim subtree is unreachable dead legacy code: two
+      independent reachability walks of the live, 138-139-handle Attack pose graph found zero
+      SkSpeedAnim nodes and only three two-input Switches, with the named handle for the subtree
+      (h1125) having zero HandleRefId references anywhere in the 16.6 MB serialized file. The real
+      ceiling on swing count is the CSV motion database's 9 slots per attack class
+      (combo/heavy/final), not the animgraph's node structure."
+    status: inferred
+    supersedes: cp2077.anims.graph.sk-speedanim-subtree-is-dead-old-belief
+    source: ModWright research
+    tags:
+      - csv-ceiling
+      - nine-slots
+      - reachability
+      - skspeedanim
+    detail: Names like heavy_attack_03, final_attack_01/02, final_attack_06..09 and combo_attack_05..09
+      are all addressable CSV slots with no clip in any mounted set — an authoring gap, not an
+      engine limit.
+  - id: cp2077.anims.graph.numframes-engine-read-question
+    claim: Whether the engine reads a clip's numFrames field directly, or derives the played sample
+      count purely from the duration field, has never been directly observed in game.
+    status: unverified
+    source: ModWright research
+    tags:
+      - numframes
+      - duration
+      - engine-behavior
+      - open-question
+    detail: "Why it matters: the shipped build carries a numFrames-vs-duration off-by-one on 44 of 96
+      entries (see cp2077.anims.pipeline.numframes-off-by-one-defect), and the source estimates the
+      cost of a lost terminal frame at 3.3-20.6 mm / 0.45-6.6 deg on drawn bones — which would break
+      exactly the terminal-pose convention the chain relies on. The cheapest resolution offered is
+      to make the question MOOT: assert the invariant `numFrames - 1 == round(duration * 30)` in the
+      builder and always fix the field, rather than proving which one the engine reads. If it must
+      be observed, the source suggests picking a clip with a large last-frame delta (safe_attack,
+      16.8 mm / 6.6 deg) and looking. A duplicate of this open question previously also sat in the
+      encoder topic and was merged here."
+  - id: cp2077.anims.graph.final-attack-04-renders-once-steering-removed
+    claim: Using a mod's own console command to bypass the finisher's steering script, the counter-3
+      slot's own final_attack_04 entry (present in the mod's katana-clone anim set) was confirmed in
+      game to resolve and render correctly — a rising slash, the katana's own combo_attack_04 shape
+      — proving the mounted set's final_attack_04 slot works and the steering script's original
+      justification (the previously mounted set lacking that entry) had expired.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - final-attack-04
+      - animsteering
+      - console-test
+      - verified
+    detail: This result licensed authoring directly into final_attack_04 and retiring the mod's finisher
+      redirect in redscript at ship time.
+  - id: cp2077.anims.graph.animsteering-is-pure-visual-redirect
+    claim: A melee weapon mod's steering script only ever touches attack counter 3 (matching literal
+      slot names MeleeComboAttack3 / MeleeFinalAttack3), and rewrites MeleeSlotData to
+      (attackType=1, comboNumber=0) = CSV(1,0) = heavy_attack_01; its blendPercent=30 knob and its
+      trailAttackSide copy are both dead in the shipped configuration (the chosen visual record's
+      durations default to 0, so the else-branch always runs; no machete record sets
+      trailAttackSide). It is therefore a pure (attackType, index) visual redirect and nothing more.
+    status: inferred
+    source: ModWright research
+    tags:
+      - animsteering
+      - heavy_attack_01
+      - meleeslotdata
+      - dead-code
+    detail: Two of its three coded effects are inert in the shipped configuration; only the (attackType,
+      comboNumber) rewrite does anything observable.
+  - id: cp2077.anims.graph.steered-finisher-was-timing-out-of-band
+    claim: The steered heavy_attack_01 finisher fires its gameplay hit about 160 ms out of band from its
+      own clip's visual contact frame, and the state exits before the clip finishes (truncated at
+      frame 36 of 42, landing 45-49 mm short of the clip's own authored end pose); playing the set's
+      own final_attack_04 instead (exactly 1.200 s, plays to its last frame) puts the hit back
+      inside vanilla's measured -27 ms to +70 ms band.
+    status: inferred
+    source: ModWright research
+    tags:
+      - steered-finisher
+      - heavy_attack_01
+      - timing
+      - truncation
+    detail: This quantifies why retiring the steering script in favor of authoring final_attack_04
+      directly was a strict improvement, not just a cosmetic preference.
+  - id: cp2077.anims.graph.gameplay-hit-lands-near-active-phase-event
+    claim: Across every vanilla family measured where records and clips are matched, the gameplay hit
+      lands within -27 ms to +70 ms of the clip's own `active` animAnimEvent_Phase event; expressed
+      as a retimer-invariant fraction, the authored contact frame should sit at attackEffectDelay /
+      startupDuration (measured as 0.899 of the startup segment for the machete-record/katana-clip
+      pairing used here) when the three-segment retimer is engaged, or at the record's absolute
+      attackEffectDelay time when the durations are 0/0/0 (whole-clip route).
+    status: inferred
+    source: ModWright research
+    tags:
+      - gameplay-hit
+      - active-phase-event
+      - contact-frame
+      - retimer-invariant
+    detail: Expressing the target as a fraction rather than an absolute time matters because
+      MeleeAttackData's attackSpeed field scales the window fields and the phase durations together,
+      so the ratio stays invariant under speed modifiers; no melee record in the game sets
+      DontScaleWithAttackSpeed.
+  - id: cp2077.anims.graph.lunge-mechanism-is-move-to-target-not-perk-leap
+    claim: "A vanilla \"blades\" perk leap and the Byakko katana's iconic-mod leap are the SAME
+      mechanism (both simply add BaseStats.CanMeleeLeap), and that flag's only gameplay consumer,
+      the meleeLeap PSM state, is structurally unreachable from a light-attack-chain finisher:
+      meleeLeap is absent from meleeFinalAttack.transitionTo and its entry condition requires a
+      charged strong-attack-hold release. The mechanism that DOES reach a light-chain finisher is
+      the ordinary, non-perk-gated enableAdjustingPlayerPositionToTarget record boolean, read by
+      MeleeAttackGenericEvents.OnEnter for every attack type including MeleeFinalAttackEvents."
+    status: inferred
+    source: ModWright research
+    tags:
+      - lunge
+      - canmeleeleap
+      - meleeleap
+      - enableadjustingplayerpositiontotarget
+      - finisher
+    detail: No token "leap" occurs anywhere in the 16.6 MB serialized player_melee.animgraph.json, and
+      no clip named *leap*/*dash*/*lunge* exists in any of the nine player-FPP melee sets — the leap
+      state's "animation" is just the engine sliding the capsule during a held charged pose.
+  - id: cp2077.anims.graph.move-to-target-lunge-geometry
+    claim: With enableAdjustingPlayerPositionToTarget=true, the move-to-target slide searches a 4.0 m
+      radius (weapon Range 2.0 + MoveToTargetSearchDistance 2.0) within a 10-degree pitch-and-yaw
+      cone of the crosshair, pulls back 0.25 m from the target's Center slot, completes over
+      attackData.attackEffectDelay seconds (0.240 s stock on the machete finisher), issues no
+      rotation (rotationDuration = -1.0), and only fires when the player's Melee Aim Assist setting
+      resolves to AllAttacks (which every selectable setting level does by default). A -45-degree
+      pitch gate applies, and the target must be an active, non-friendly puppet closest to the
+      crosshair.
+    status: inferred
+    source: ModWright research
+    tags:
+      - lunge
+      - move-to-target
+      - attackeffectdelay
+      - aim-assist
+      - adjustplayerposition
+    detail: "Practical travel range given the pull-back is 0 to about 3.75 m, target-relative; the mod's
+      own in-game-tested tuning of this record (distance and attackEffectDelay) across several
+      deploys treated this geometry as confirmed and adjusted only the specific numbers. On the
+      settings chain: AimAssistMelee_Default sets moveToTargetEnabledAttacks = 2 (AllAttacks), and
+      Settings_MeleeCombat maps ALL THREE user aim-assistance levels (light, standard and heavy)
+      onto the same AimAssistConfigPreset_MeleeCombat, whose default_index is 2 = Standard — so on a
+      default install IsMoveToTargetEnabled reduces to the single record boolean and the attack type
+      is never consulted."