modwright 0.1.0

package/knowledge/cyberpunk2077/anims.pipeline.yaml

@@ -0,0 +1,352 @@
+game: cyberpunk2077
+topic: anims.pipeline
+title: Blender to GLB to WolvenKit .anims round trip for custom FPP melee animations
+facts:
+  - id: cp2077.anims.pipeline.cli-export-anims-old-belief
+    claim: An early project note stated that WolvenKit.CLI cannot export .anims to GLB, making the GLB
+      half of the round trip a GUI-only job.
+    status: contradicted
+    source: ModWright research
+    tags:
+      - wolvenkit
+      - cli
+      - export
+      - anims
+      - glb
+    detail: "Superseded the same day: the missing ingredient was the -gp flag, not a real CLI
+      limitation. Replaced by cp2077.anims.roundtrip.cli-export-strips-root-motion, which carries
+      both the working command form and the root-motion caveat. The GUI-only IMPORT half of the
+      round trip is recorded separately at cp2077.anims.roundtrip.import-is-gui-only."
+  - id: cp2077.anims.pipeline.glb-export-requires-animations-checkbox
+    claim: Exporting an authored action from Blender back to a Cyberpunk GLB requires selecting the
+      ARMATURE object in Object Mode and ticking "Animations" (export_poses) in File -> Export ->
+      Cyberpunk GLB; without it the exporter takes the mesh path and fails with "No meshes
+      selected".
+    status: inferred
+    source: ModWright research
+    tags:
+      - blender
+      - export
+      - glb
+      - cyberpunk-io-suite
+      - animations
+    detail: Leave "Export Float Tracks" ON and any action filter OFF, or only the active action gets
+      written to the GLB.
+  - id: cp2077.anims.pipeline.cp77-addon-importer-required-for-anims
+    claim: A donor .anims GLB must be imported with the Cyberpunk IO Suite's
+      `bpy.ops.io_scene_gltf.cp77(scripting=True, import_tracks=True)`, never with Blender's stock
+      `bpy.ops.import_scene.gltf`.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - blender
+      - cp77-addon
+      - import
+      - anims
+      - float-tracks
+      - stock-gltf
+    detail: A CP2077 animation entry carries 23 float tracks (allowFeetIk, enableLeftFootIk,
+      chestSpineStretchFactor, ...) as non-bone fcurves plus 12-14 action custom properties
+      (rootMotionType, constTrackKeys, animEvents, optimizationHints, ...). The stock importer drops
+      all of this. A block build exported through the stock path teleported the player and made V
+      fall through the floor.
+  - id: cp2077.anims.pipeline.float-track-carries-model-space-position
+    claim: Among a clip's 23 float tracks are modelSpacePositionX/Y/Z, the player's model-space
+      position; a clip that loses this track data on import teleports the player.
+    status: inferred
+    source: ModWright research
+    tags:
+      - float-track
+      - model-space-position
+      - teleport
+      - stock-gltf
+    detail: Discovered while diagnosing the stock-glTF-importer teleport defect above; this is the
+      specific mechanism by which a clip missing its non-bone track data moves the player character.
+  - id: cp2077.anims.pipeline.cubicspline-import-failure
+    claim: Keyframes inserted from a Python script default to BEZIER interpolation, which Blender's glTF
+      exporter writes as CUBICSPLINE samplers; WolvenKit's importer rejects those with "The given
+      key 'CUBICSPLINE' was not present in the dictionary."
+    status: inferred
+    source: ModWright research
+    tags:
+      - blender
+      - cubicspline
+      - interpolation
+      - import-failure
+      - keyframe
+    detail: "Fix, belt and braces: set `bpy.context.preferences.edit.keyframe_new_interpolation_type =
+      'LINEAR'` before keying, then force every existing key's interpolation to LINEAR after keying.
+      A healthy GLB reports only STEP and LINEAR samplers (one verified example: 22696 STEP / 7400
+      LINEAR, zero CUBICSPLINE). Vanilla-imported curves are already LINEAR/STEP, which is why an
+      untouched round trip imports fine and a freshly-keyed one does not."
+  - id: cp2077.anims.pipeline.compare-curves-by-bone-name-not-index
+    claim: "Offline verification of a round-tripped .anims file must compare motion curves by BONE NAME,
+      never by node index, because the GLB export reorders skeleton node indices (one measured
+      example: RightHand moved from index 25 to 47)."
+    status: inferred
+    source: ModWright research
+    tags:
+      - glb
+      - node-index
+      - bone-name
+      - verification
+      - reorder
+    detail: Index-based comparison of the same bone before and after a round trip shows bogus
+      ~180-degree deltas that are purely an artifact of the reordering, not a real pose change.
+  - id: cp2077.anims.pipeline.roundtrip-baseline-gate
+    claim: A clean, unedited .anims round trip through Blender (import via the cp77 addon, export back
+      to GLB, WolvenKit reimport) reproduces all 97 entries with identical names, durations and
+      animationType, and curve values identical to float rounding (max component delta measured
+      1.4e-4).
+    status: inferred
+    source: ModWright research
+    tags:
+      - round-trip
+      - baseline
+      - gate
+      - verification
+      - float-rounding
+    detail: "Blender bakes denser keys than the source cooked file (source file 515KB -> 726KB after the
+      round trip; GLB size drops from 18.8MB to 9.4MB — this is fine). The only structural delta on
+      a clean round trip is that the importer adds a `motionExtraction: {HandleRefId: -1}` null
+      handle where the original omitted the field; this is harmless."
+  - id: cp2077.anims.pipeline.animevents-survive-roundtrip-byte-identical
+    claim: animAnimEvent_Phase events (a clip's startup/active/recover segment markers, stored as
+      startFrame + durationInFrames in a sibling "events" container next to the clip's ".animation"
+      data) survive the Blender GLB round trip byte-identical, even on clips whose keyframes were
+      actively rewritten.
+    status: inferred
+    source: ModWright research
+    tags:
+      - animevents
+      - phase-markers
+      - round-trip
+      - cp77-addon
+      - custom-properties
+    detail: "Measured across the whole vanilla katana set: 184 events across 97 entries before, 184
+      after, zero changed — including 26 events on 11 clips whose keyframes the block builder
+      actually rewrote. The cp77 addon carries these events in Blender action custom properties,
+      which is why they survive edits to the bone curves untouched."
+  - id: cp2077.anims.pipeline.numframes-off-by-one-defect
+    claim: Vanilla .anims entries hold the invariant `numFrames - 1 == duration * 30` (measured on
+      401/401 entries across six vanilla sets); one mod's pipeline instead wrote `duration * 30` for
+      numFrames while preserving duration unchanged, producing an off-by-one on 44 of 96 shipped
+      entries, including combo_attack_01/02/03.
+    status: inferred
+    source: ModWright research
+    tags:
+      - numframes
+      - duration
+      - off-by-one
+      - invariant
+      - defect
+    detail: Whether the game engine actually reads numFrames directly, or derives the sample count
+      purely from duration, is a separate open question — see
+      cp2077.anims.graph.numframes-engine-read-question (unverified). The fix applied was to assert
+      the invariant in the builder and correct the field regardless of whether the engine cared.
+  - id: cp2077.anims.pipeline.serialize-diff-offline-verification-workflow
+    claim: The standard offline verification workflow for a rebuilt .anims file is to `convert
+      serialize` both the original and the rebuilt file to JSON, diff entry names, durations and
+      animationType, then compare motion curves by bone name (never node index).
+    status: inferred
+    source: ModWright research
+    tags:
+      - wolvenkit
+      - serialize
+      - json
+      - diff
+      - workflow
+    detail: This workflow, plus the end-to-end pose re-measurement, replaces a game launch for almost
+      every structural or pose question about a rebuilt .anims file.
+  - id: cp2077.anims.pipeline.gui-import-reads-project-raw-folder-not-arbitrary-glb
+    claim: The WolvenKit GUI's Import action always consumes the project's own raw folder path for the
+      resource being imported (e.g. `<Project>\source\raw\mod\<mod>\anims\<set>.anims.glb`), not
+      whatever GLB the build tooling last wrote elsewhere; staging a new build requires copying the
+      staging GLB over that raw-folder path (MD5-verified) before telling the user to import.
+    status: inferred
+    source: ModWright research
+    tags:
+      - wolvenkit
+      - gui
+      - import
+      - raw-folder
+      - staging
+      - stale-import
+    detail: "Caught after a \"no difference\" deploy: the staging GLB was current but the raw-folder
+      copy was from that morning, the import \"succeeded\" against the stale copy, and two deploys
+      shipped stale content while every downstream check passed (a deploy script's baseline check
+      only catches a never-imported GLB, not a stale one). Diagnose this class of failure by
+      serializing the imported .anims and checking a field only the new build could have set."
+  - id: cp2077.anims.pipeline.numconstankeys-dense-encoding-not-a-defect
+    claim: A rebuilt .anims entry that reports `numConstAnimKeys = 0` (every joint stored on every
+      frame, dense encoding) after a round trip is not itself a fault as long as the end-to-end pose
+      check passes — vanilla `melee_first_equip` ships encoded the same dense way.
+    status: inferred
+    source: ModWright research
+    tags:
+      - numconstankeys
+      - dense-encoding
+      - gate
+      - false-positive
+    detail: This was initially graded a hard build failure by an overly strict heuristic; it was found
+      to be a cosmetic difference in how identical data is packed, not missing data.
+  - id: cp2077.anims.pipeline.content-diff-preferred-over-byte-md5
+    claim: "Repeated GLB rebuilds from the same content are NOT byte-reproducible: the Blender/cp77
+      exporter scrambles channel ORDER run-to-run on some clips (a documented case: exactly the four
+      sway additive clips), values remaining bit-identical. Regression gates should diff channels
+      matched by bone+path (content diff), never compare whole-file byte MD5."
+    status: inferred
+    source: ModWright research
+    tags:
+      - content-diff
+      - byte-md5
+      - regression-gate
+      - channel-order
+      - glb-export
+    detail: Setting PYTHONHASHSEED=0 does not fix the channel-order nondeterminism. The project's
+      `_glb_content_diff.py` tool matches channels by bone name and property path specifically to
+      make this gate reliable.
+  - id: cp2077.anims.pipeline.wolvenkit-importer-numextrajoints-drops-last-joints
+    claim: WolvenKit's animation importer (AnimationTools.cs::PutAnimations) computes `jointsCountActual
+      = numJoints - numExtraJoints`, where numExtraJoints is read from the GLB action's
+      custom-property "extras" on each animation, and drops that many joints from the end of the rig
+      regardless of what the WolvenKit project file itself specifies; a GLB whose extras still carry
+      a donor clip's inherited numExtraJoints value (e.g. 1) silently imports one fewer joint than
+      it should.
+    status: inferred
+    source: ModWright research
+    tags:
+      - wolvenkit
+      - importer
+      - numextrajoints
+      - glb-extras
+      - missing-joints
+      - victim-anims
+    supersedes: cp2077.anims.pipeline.dense-per-frame-baking-imports-more-reliably
+    detail: "Found on victim-lift animation clips inheriting a donor's `numExtraJoints: 1` GLB extras
+      value: they imported 69/71 rig bones (missing RightHandPinky3 and Root) while a from-scratch
+      player-authored GLB with `numExtraJoints: 0` imported all 152/152 clean. Three earlier
+      attempted fixes (project-file numExtraJoints, a small Root offset, dense baking alone) never
+      touched this GLB-extras field and were therefore byte-for-byte no-ops on the symptom."
+  - id: cp2077.anims.pipeline.wolvenkit-importer-rootmotiontype-consumes-root-joint
+    claim: WolvenKit's importer (Tools/Animation/AnimRootMotion.cs::ExtractRootMotion), for any
+      rootMotionType other than None/Unknown, takes the Root joint's translation/rotation as the
+      root-motion source and never writes Root as a regular joint channel; setting an action's
+      rootMotionType to "Unknown" makes the importer instead keep the project file's existing
+      motionExtraction data verbatim and treat Root as an ordinary joint.
+    status: inferred
+    source: ModWright research
+    tags:
+      - wolvenkit
+      - importer
+      - rootmotiontype
+      - root-motion
+      - extras
+    detail: 'Fix applied in the clip-editing script: set numExtraJoints=0, numExtraTracks=0, and
+      rootMotionType="Unknown" on every action before export, and gate the written GLB on both the
+      extras values and which bones actually carry channels. All three prepared victim GLBs then
+      reported "GLB EXTRAS OK" and imported their full 71/71 joint count.'
+  - id: cp2077.anims.pipeline.dense-per-frame-baking-imports-more-reliably
+    claim: "A clip where every bone is re-keyed with evaluated values on every single frame (a dense
+      bake) imports its full joint count via WolvenKit's raw per-frame path (one measured case:
+      152/152 bones, numConstAnimKeys 0), while sparse or padded curves from a less exhaustive
+      keying approach can take an import path that silently drops the rig's first and last joints."
+    status: contradicted
+    source: ModWright research
+    tags:
+      - dense-bake
+      - per-frame
+      - joint-coverage
+      - import-reliability
+      - dead-belief
+    detail: "Kept as the belief held on 2026-09-02 morning. DISPROVEN the same afternoon: \"The
+      dense-bake fix did not take either\" — the rebuilt victim clips still imported 69/71 bones
+      after a full dense bake, and the source's own summary is that \"the three earlier fixes
+      (project-file numExtraJoints, Root 0.1 mm, dense bake) never touched the extras, which is why
+      they were byte-for-byte no-ops on the symptom.\" The real cause is the GLB action extras — see
+      cp2077.anims.pipeline.wolvenkit-importer-numextrajoints-drops-last-joints. The 152/152
+      dense-baked player set is still a true observation; it simply does not explain the victim
+      sets, which were also dense-baked and still dropped two joints."
+  - id: cp2077.anims.pipeline.attach-frame-90-degree-rotation-correction
+    claim: The in-game FPP weapon attachment frame is `game_weapon_world = bone_world @ Rotation(-90
+      deg, local X)`; a Blender preview workbench that Child-Of's the weapon mesh to WeaponRight
+      with an IDENTITY inverse gets the weapon's POSITION right but its ROTATION 90 degrees wrong.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - attachment-frame
+      - weaponright
+      - child-of
+      - rotation
+      - workbench
+      - probe
+    detail: "Confirmed because the identical 90-degree discrepancy appeared on an UNTOUCHED vanilla clip
+      (melee_idlepose) too, proving the preview frame was wrong rather than the authored data. Fix:
+      set the Child Of inverse to Rotation(-90 deg, X); any weapon-pose write to bones must apply `X
+      @ ATTACH^-1` so a desired world matrix X lands as X in game."
+  - id: cp2077.anims.pipeline.file-layout-weapon-anim-sets
+    claim: Player FPP melee anim sets live under `base\animations\weapon\<weapon>\` as per-gender files
+      `pwa_<weapon>.anims` (female) / `pma_<weapon>.anims` (male); all player melee weapon sets
+      share the same 152-joint rig, which is what makes cross-weapon donor grafting mechanically
+      straightforward.
+    status: inferred
+    source: ModWright research
+    tags:
+      - file-layout
+      - anim-set
+      - pwa
+      - pma
+      - rig
+      - weapon-family
+    detail: Motion data is stored as compressed slices in animationDataChunks[i] (base64 in the
+      serialized JSON), addressed per entry by animBuffer.dataAddress {unkIndex, fsetInBytes,
+      zeInBytes}; WolvenKit also keeps a per-entry tempBuffer copy. `default_melee_weapon.anims`
+      (non-prefixed) is a separate, ungated, always-mounted fallback set distinct from any
+      per-weapon-family pwa_/pma_ set.
+  - id: cp2077.anims.pipeline.entry-naming-convention
+    claim: "Entries inside a player melee .anims set follow a fixed naming convention. The CSV motion
+      database defines the addressable names: combo_attack_01..09, heavy_attack_01..06 (plus
+      melee_hack_attack, mantisblade_special_heavy, one_punch_heavy_attack) and final_attack_01..09.
+      Alongside them a set carries block/block_start/block_end/block_attack, add_block_*
+      (directional block reactions), block_deflect_left/right, hold_start_01 +
+      hold_start_offscreen_01/02, hold_loop_01/02, melee_idlepose/melee_safepose/melee_crouchpose
+      and their transitions, melee_equip/melee_first_equip/melee_unequip, the melee_slide_* and
+      melee_sprint_* locomotion entries, and the
+      slide/crouch/jump/sprint/fall/throw/dodge/equip/safe attack variants — every base attack entry
+      paired with `_hit` and `_deflect` suffixed variants."
+    status: inferred
+    source: ModWright research
+    tags:
+      - naming-convention
+      - entry-names
+      - combo-attack
+      - heavy-attack
+      - final-attack
+    detail: "Not every numbered slot has a clip in every set: heavy_attack_03, final_attack_01/02,
+      final_attack_06..09 and combo_attack_05..09 are addressable CSV names with no clip in any
+      mounted set (see cp2077.anims.graph.real-swing-ceiling-is-nine-slot-csv). combo_attack_04 DOES
+      exist in the vanilla katana set (a 4th diagonal slash) and therefore in this mod's
+      katana-clone set, as well as in default_melee_weapon.anims (where it is the left-punch
+      content) — an earlier phrasing of this fact wrongly said it existed only in
+      default_melee_weapon.anims. In vanilla katana, final_attack_04 is byte-identical to
+      combo_attack_04 but sits in a distinct buffer (BufferId 75 vs 76), so re-authoring one does
+      not alias into the other."
+  - id: cp2077.anims.pipeline.byte-splice-transplant-approach-dead
+    claim: "An early transplant approach — decoding a source .anims motion chunk, slicing its bytes,
+      appending them to a target entry's chunk, and repointing the target's dataAddress (a
+      byte-growing cross-file splice) — was silently rejected by the game engine: the modded file
+      loaded, but the spliced entry played unchanged vanilla content, with no error anywhere."
+    status: contradicted
+    source: ModWright research
+    tags:
+      - transplant
+      - byte-splice
+      - chunk-growing
+      - dead-end
+      - silent-rejection
+    detail: "A decisive bisect ruled out several other explanations: an IN-FILE repoint with no new
+      bytes (redirecting one existing entry's dataAddress to another existing entry's data) DID work
+      and rendered correctly in game, while any approach that grew the file's chunk data did not.
+      This dead end was abandoned in favor of the full Blender GLB round-trip pipeline (author in
+      Blender, export a whole GLB, WolvenKit reimport) documented in the rest of this file — no
+      single fact \"replaces\" it, so no supersedes id is given."

package/knowledge/cyberpunk2077/anims.roundtrip.yaml

@@ -0,0 +1,222 @@
+game: cyberpunk2077
+topic: anims.roundtrip
+title: Round-tripping .anims through wolvenkit and Blender - known corruptions
+facts:
+  - id: cp2077.anims.roundtrip.cli-export-strips-root-motion
+    claim: "wolvenkit CLI can export .anims to GLB headlessly (positional path plus -gp), but it
+      SILENTLY STRIPS ROOT MOTION by default, logging only \"Root motion export: disabled\". A
+      clip's world travel simply vanishes from the GLB and every measurement taken from it is wrong.
+      Enable it with \"AnimationExportArgs\" incRootMotion true in the CLI's appsettings.json."
+    status: verified
+    source: ModWright field verification
+    tags:
+      - cli
+      - anims
+      - export
+      - root-motion
+      - silent-failure
+      - appsettings
+    supersedes: cp2077.anims.pipeline.cli-export-anims-old-belief
+    detail: "The -o output directory must already EXIST or the export dies with \"fill in an output
+      path\". Corrects an earlier note claiming the CLI could not export .anims at all (kept as
+      cp2077.anims.pipeline.cli-export-anims-old-belief). MERGED from a mod project's record of the
+      same command, which adds: the path argument must be POSITIONAL (with -p instead it fails
+      misleadingly with \"Exporting mesh files with materials requires --gamepath to be set\"); -gp
+      is what lets the archive manager resolve the skeleton rig (a copy of the rig also sits in the
+      WolvenKit depot at MaterialRepositoryPath); a successful run logs \"Found 88 animations to
+      export, using rig base\\characters\\entities\\player\\player_woman_skeleton.rig\"; and donor
+      acquisition therefore no longer needs a GUI trip."
+  - id: cp2077.anims.roundtrip.rm-export-timeline-is-normalised
+    claim: In a root-motion GLB export the ROOT timeline is normalised to 0..1 seconds, NOT clip time.
+      Reading extraction timing off the GLB therefore time-squashes the motion by the clip's
+      duration. Read timing from the serialized .anims instead.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - anims
+      - export
+      - root-motion
+      - timing
+      - measurement
+    detail: Cost a full authoring round. motionExtraction (animSplineCompressedMotionExtraction)
+      posKeysData and rotKeysData are 16-byte knots, u16 t_norm then u16 flags then three f32, where
+      t is t_norm/65535 times duration and the values are Root translation in the rig's LOCAL frame.
+  - id: cp2077.anims.roundtrip.simd-extra-joints-export-garbage
+    claim: A clip whose animation buffer is animAnimationBufferSimd AND which has one or more extra
+      joints exports to GLB as silent garbage - every bone carries a bogus constant scale fcurve and
+      the evaluated pose collapses. Compressed buffers with extra joints are fine, and Simd with
+      zero extra joints is fine. It is the COMBINATION, not the extra-joint count alone.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - anims
+      - export
+      - glb
+      - corruption
+      - simd
+      - wolvenkit-bug
+      - blender
+    detail: Under full inherit-scale the bogus scale compounds down 152 bones until every bone's
+      evaluated head reads as a unit vector, no exception is raised, and a render is an empty frame.
+      Every PLAYER finisher clip in the game is Simd with one extra joint, so none can currently be
+      round-tripped; NPC-side finisher clips are Compressed and export clean. The extra joints are
+      syncTrajectory sync-scene tracks, not bones, so no rig override helps. CHEAP UNIVERSAL GATE -
+      after importing any donor, assert every pose bone's matrix_basis scale is (1,1,1) and that the
+      pose actually moves. The anim pipeline keys loc and rot only, so any nonzero scale channel on
+      a donor is by definition corruption.
+  - id: cp2077.anims.roundtrip.import-writes-bad-fallback-indices
+    claim: The .anims GUI import rewrites fallbackFrameIndices on REBUILT clips to out-of-range values,
+      which HARD CRASHES the game the instant such a clip plays. Each clip's
+      animBuffer.fallbackFrameIndices is two ints indexing the set-level fallbackAnimDescIndexes
+      array.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - anims
+      - import
+      - crash
+      - corruption
+      - wolvenkit-bug
+      - gate
+    detail: "Vanilla mantis clips use small in-range values such as [4,5] or [6,7]; the importer rewrote
+      rebuilt clips to [78,79] while leaving untouched clips alone, and the engine then read index
+      78 of a 10-element array. The compile was clean and the bone data sound. The fallback ARRAYS
+      survive import identical to vanilla, so the fix is byte-safe: restore each rebuilt clip's
+      indices in the serialized JSON, and gate that every clip's indices are within the bounds of
+      fallbackAnimDescIndexes before packing."
+  - id: cp2077.anims.roundtrip.import-stale-extra-joint-count
+    claim: The .anims import copies the EXISTING clip's extra-joint count onto a rebuilt clip while
+      encoding every GLB bone as a real channel. The engine then reads the last real bone as a sync
+      track, the mesh bounds straddle the frustum, and the body flashes on and off in game. A
+      rebuilt clip from a GLB with no sync nodes MUST carry numExtraJoints 0 and empty
+      extraDataNames.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - anims
+      - import
+      - corruption
+      - culling
+      - wolvenkit-bug
+      - gate
+    detail: Symptom is numJoints 71 with extra 1 on a 71-bone rig. Nothing crashes and wolvenkit exports
+      it fine. Synced finishers still align with no syncTrajectory on either side, because the
+      workspot syncOffsets carry it.
+  - id: cp2077.anims.roundtrip.import-drops-joint-channels
+    claim: The .anims importer is driven by the GLB's per-animation EXTRAS (the Blender action's custom
+      properties), NOT by the project file. A donor-inherited numExtraJoints of 1 makes it write
+      only 70 of 71 rig joints, dropping the last; and any rootMotionType other than None or Unknown
+      makes it consume the Root joint's keys as a re-invented motionExtraction and write no Root
+      joint at all. The engine reads garbage for a joint with no entry and the mesh culls in and
+      out.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - anims
+      - import
+      - corruption
+      - glb-extras
+      - wolvenkit-bug
+      - gate
+    detail: "Cost three launches and three wrong fixes - aimed at the project file, the Root value, and
+      key density - because none of them touched the extras. Before exporting a clip re-authored
+      from a donor, set the action's numExtraJoints to 0 and its rootMotionType to \"Unknown\"
+      (Unknown means keep the project file's existing extraction verbatim AND treat Root as a
+      regular joint). Then gate the written GLB's extras and channel targets, and gate the imported
+      set by re-exporting it and counting channel targets. GENERALISES: when an importer misbehaves
+      on a round-tripped file, diff the round-trip's METADATA against a file that imports cleanly
+      before touching the data."
+  - id: cp2077.anims.roundtrip.import-preserves-extraction-if-root-static
+    claim: With "Use existing file", the .anims importer PRESERVES the existing clip's motionExtraction
+      as long as the GLB's Root does not move. Author bones root-relative with Root keyed STATIC and
+      a vanilla extraction survives verbatim. A GLB whose Root animates gets its extraction
+      re-encoded, and both dense and sparse Root keys produce broken results.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - anims
+      - import
+      - root-motion
+      - motion-extraction
+      - gui
+    detail: Dense Root keys produced a wrong-curve spline; sparse Root keys a corrupt 66 KB one, which
+      then failed re-export with "Motion extraction in joint 2, out of range". Gate on byte-equality
+      of the extraction.
+  - id: cp2077.anims.roundtrip.import-drops-animevents
+    claim: The .anims importer does not carry the Blender addon's animEvents action property. A rebuilt
+      clip inherits the events of whatever DONOR action was copied, so the events must be patched
+      back into the serialized JSON after import.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - anims
+      - import
+      - animevents
+      - corruption
+  - id: cp2077.anims.roundtrip.import-is-gui-only
+    claim: There is no headless route for importing .anims. The CLI import verb refuses them ("as Mesh")
+      and the CLI build verb crashes. The wolvenkit GUI import is the only working path, so an anims
+      pipeline cannot be fully automated.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - anims
+      - import
+      - cli
+      - gui
+      - limitation
+    detail: "MERGED from a mod project's record of the same limitation, which adds the exact failure
+      text and the argument shape: `import -k` routes a .glb to the MESH importer and dies with
+      \"Failed to rebuild with buffers: x.anims (as Mesh)\"; there is no -gp and no anims-specific
+      argument on `import`, and -o must be the folder that directly CONTAINS the target .anims (it
+      does not mirror the raw tree from a single-file argument). The practical loop for one
+      animation iteration is therefore: bake headless -> ONE GUI import click -> pack headless."
+  - id: cp2077.anims.roundtrip.use-the-addon-importer
+    claim: To import a donor .anims GLB into Blender, use the Cyberpunk IO Suite importer -
+      bpy.ops.io_scene_gltf.cp77 with scripting and import_tracks enabled - never
+      bpy.ops.import_scene.gltf. The stock importer silently drops the 23 float tracks and roughly
+      13 action custom properties that every clip carries.
+    status: verified
+    source: ModWright field verification
+    tags:
+      - anims
+      - blender
+      - import
+      - addon
+      - float-tracks
+      - silent-failure
+    detail: "Dropped data includes allowFeetIk, enableLeftFootIk/RightFootIk, cameraUpOffset,
+      rootMotionType, constTrackKeys, animEvents and optimizationHints. The rebuilt entry comes back
+      hasRawRotations 1 with numConstTrackKeys 0, and in game the missing foot-IK flags TELEPORT THE
+      PLAYER - black screen, streaming reload, V under the world or underwater. Cost a full launch.
+      Gate on the encoding fields, not just names and durations. GENERALISES: when an addon ships
+      its own importer for a format, the stock one is not a substitute - the addon's exists to carry
+      the engine-specific extras."
+  - id: cp2077.anims.roundtrip.encoder-rotation-noise
+    claim: The wolvenkit anims encoder keeps POSITIONS exact (0.00 mm) but degrades ROTATIONS on the
+      gun-space chain and IK JNTs by 1.3 to 3.3 degrees. The ordinary arm chain encodes clean, under
+      0.3 degrees. Constant channels encode exactly, which is why positions survive.
+    status: inferred
+    source: ModWright research
+    tags:
+      - anims
+      - encoder
+      - rotation
+      - precision
+      - noise
+      - sway
+    detail: "A shipped weapon's orientation was up to half phantom noise: an authored turn of 2.2
+      degrees against 2.1 to 2.5 degrees of encoder error. No gate measuring the authored or
+      re-exported data at the same points can see it as motion. Practical rule - author varying
+      rotation only into arm-chain bones, keep weapon-placement and IK-bone rotation channels
+      CONSTANT, and carry motion in translations. MERGED from a mod project's measurement of the
+      same effect, which gives the per-bone numbers on the four ambient-sway additive clips:
+      worst-frame arms_gun_space 2.13 deg (add_melee_idle) / 2.50 deg (add_melee_idle_combat), the
+      four Torso_*Arm_Hand_IK_JNT bones 1.3-3.3 deg, LeftArm/RightArm only 0.11-0.28 deg, and EVERY
+      position channel 0.00 mm; the authored turn inside add_melee_idle was itself only 2.18 deg.
+      Status is INFERRED, not verified: both sides are offline per-bone script measurements
+      (_encoder_audit.py), not an in-game observation. SCOPE: the damage applies to RE-AUTHORED
+      clips only — see cp2077.anims.encoder.damage-scoped-to-reauthored-clips-not-untouched-ones and
+      cp2077.anims.encoder.reauthoring-collapses-constant-channels for the mechanism, and
+      cp2077.anims.encoder.sway-gunrot-const-fix-verified-in-game for the fix that removes it at
+      source."